Skip to content

SkillSystem.md

Latest commit

 

History

History
67 lines (45 loc) · 3.8 KB

SkillSystem.md

File metadata and controls

67 lines (45 loc) · 3.8 KB
Raw

SkillSystem

The authoritative conventions for skills in this repo. Read before creating, editing, or validating a skill. The CreateSkill skill orchestrates the lifecycle; this doc is the spec it enforces.

What a skill is

A skill is a directory skills/<Name>/ containing a SKILL.md. It loads by existing — there is no marketplace or plugin registration in this repo (skills/.claude-plugin/, per-skill plugin.json are not used). Creating SKILL.md is the whole step.

Frontmatter

See skills/CreateSkill/References/Frontmatter.md for the unified frontmatter superset. The rules below are this repo's authoring policy.

---
name: SkillName
description: [What it does]. USE WHEN [intent triggers]. NOT FOR [confusable alternative].
---
  • name: — TitleCase, matches the directory.
  • description: — single line, under 1024 chars, contains a USE WHEN clause of intent triggers, and a NOT FOR clause when the skill shares vocabulary with a confusable neighbor. Written for the model deciding whether to invoke, not for a human. No legacy triggers:/workflows: arrays.
  • allowed-tools: — optional; include only to genuinely constrain tools.

Naming — TitleCase

TitleCase (PascalCase) for everything:

Component Format Example
Skill directory TitleCase CreateSkill
Workflow files TitleCase.md Create.md, UpdateInfo.md
Reference docs TitleCase.md ApiReference.md
Tool files TitleCase.ts ManageServer.ts
Help files TitleCase.help.md ManageServer.help.md

SKILL.md is the one all-caps exception.

Private skills use a leading-underscore ALLCAPS name (_DOTFILES) — anything identity-, customer-, or environment-bound that must not be shared publicly. When in doubt, build private first; promoting _Foo → Foo later is easy, un-leaking a public skill is not.

Structure — flat, 2 levels max

skills/<Name>/SKILL.md
skills/<Name>/Workflows/File.md
skills/<Name>/Tools/File.ts
skills/<Name>/References/File.md

Context/reference docs go in the skill root or References/ — never a Context/ or Docs/ subdir, never backups/. Keep SKILL.md under ~500 lines; extract encyclopedic content to References/.

Required body sections

  • ## Workflow Routing — table mapping trigger → workflow file, for skills that have workflows. Every routed file must exist; every workflow file must be routed; names match filenames exactly.
  • ## Gotchas — the highest-density section. API quirks Claude doesn't know, common mistakes, non-obvious ordering, silent-failure edge cases. Accumulates: after any failure, add the lesson.
  • ## Examples — 2-3 concrete usage patterns.

Authoring style — ideal-state (WHAT, not HOW)

Write bodies and workflows as ideal state: the WHAT (testable outcomes of a done deliverable), the CONSTRAINTS, and the TOOLS — then trust the model to find HOW. Numbered step-lists that choreograph reasoning for open-ended work cap a capable model. Four things ARE legitimate HOW and belong in skills: safety-gates, verified gotchas, tool-contracts (exact invocation recipes), output-format contracts. Deterministic *.ts tools are exempt.

Cut intensifier-only lines: stating a rule once IS the instruction. MANDATORY/CRITICAL/a third restatement add volume, not constraint. Delete any line whose only content is shouting a rule stated elsewhere.

BPE (bitter-lesson) check

Before finalizing, ask: would a smarter model make this skill unnecessary? Keep anti-fragile skills (verification harnesses, tool wrappers, accumulated gotchas, deterministic scripts). Question fragile ones (reasoning orchestrators, format parsers, retry cascades). Focus on knowledge Claude can't derive and tools it can't replicate.