| name | Skill Development |
| description | How to author a Claude Code Agent Skill — SKILL.md structure, routing-optimized descriptions, progressive disclosure, valid frontmatter fields, bundling scripts/reference files. Use when creating a new skill, writing or fixing a SKILL.md, deciding what belongs in frontmatter, splitting an oversized skill into reference files, or debugging why a skill never triggers. |
| disable-model-invocation | true |
| allowed-tools | Read, Write, Edit, Grep, Glob |
Skill Development
Procedure for authoring Claude Code Agent Skills. A skill is a directory with a SKILL.md file; optional bundled scripts and reference .md files sit beside it and load only when needed.
What a skill is (one paragraph)
At startup Claude preloads only the name + description of every installed skill into its system prompt. When a task matches, Claude reads the full SKILL.md body into context. Bundled files (reference/*.md, scripts/*) are read only when the body points to them. This is progressive disclosure: metadata → body → bundled files. Design each level to be the smallest thing that lets Claude decide whether to go deeper.
Build workflow
- Start from a real gap. Author a skill only for a capability Claude currently fumbles — a workflow it gets wrong, procedural knowledge it lacks, org context it can't infer. Don't pre-write skills for hypothetical tasks.
- Create the directory + SKILL.md.
skills/<kebab-name>/SKILL.md. Directory name is the on-disk identity — don't rename it after wiring.
- Write the frontmatter (see below). The
description is the single highest-impact line — write it as a routing rule, not a summary.
- Write the body as what to do, not narration. Numbered procedures, concrete examples, a Gotchas section.
- Keep it lean. Target under 500 lines. When it grows past that (or when some content is only relevant in a narrow sub-case), move detail into sibling
reference/*.md files and link them.
- Test the trigger. Give Claude a request that should fire the skill and confirm it loads. If it doesn't, the description is the problem — add the missing trigger words. Then watch it use the skill on a real task and fold successes/mistakes back into the body.
Frontmatter — valid fields only
Claude Code reads a fixed set of keys and silently ignores unknown ones (so a typo'd field just disappears — no error).
name: Skill Name
description: >
What it does. Use when <triggers>.
disable-model-invocation: true
user-invocable: false
argument-hint: "[arg]"
allowed-tools: Read, Grep
context: fork
model: sonnet
Scope allowed-tools Bash where you can: Bash(git *), Bash(python3 *). Never list a tool the procedure doesn't actually run.
The description IS the routing rule
The description is Claude's decision engine for whether to load the skill — not documentation for humans. Write it for the model.
Shape: <what it does>. Use when <concrete trigger scenarios + words a user would actually type>.
- Put the primary use case first — the listing truncates around 1,536 chars.
- Pack in the literal trigger phrases and command names a user says ("run the docs commands", "/forge:docs-audit", "add JSDoc"). Claude matches on these.
- Name what it does NOT cover if a sibling skill is easy to confuse with.
Worked example — turning a weak description into a routing rule:
description: Documentation standards for the project.
description: >
Documentation standards and code-to-docs sync — JSDoc/TSDoc, README/CHANGELOG
structure, auto-generated API reference, staleness detection. Use when writing or
reviewing docs, adding JSDoc to exported functions, structuring a docs/ tree, or
running /forge:docs-status, /forge:docs-audit, /forge:docs-update.
Progressive disclosure — split when oversized
The body stays in context for the rest of the turn once loaded, so every line is recurring token cost. Keep SKILL.md a lean overview + navigation; push depth into bundled files.
When to split a section out to reference/<topic>.md:
- The
SKILL.md is heading past ~500 lines.
- A section is only relevant in a narrow sub-case (e.g. one specific file format).
- Two large sections are mutually exclusive — a task needs one or the other, never both.
Link from the body with a resources section so Claude knows the file exists and when to read it:
## Additional resources
- For the OWASP Top-10 mapping, see [reference/owasp.md](reference/owasp.md)
- For fillable-PDF form handling, see [reference/forms.md](reference/forms.md)
Claude reads a linked file only when the current task needs it — bundled context is effectively unbounded because it isn't all paid for up front.
Bundling scripts — deterministic work belongs in code
If a step is deterministic and error-prone for a model (sorting, parsing, extracting PDF form fields, computing a hash), ship a real runnable script in scripts/ and tell the body to run it rather than reason through it. In the body, be explicit whether Claude should execute a file or read it as reference — the two modes look identical on disk.
Only add a script if it is complete and runnable. A stub script is worse than inline prose guidance.
Gotchas
- Unknown frontmatter fields vanish silently. Claude Code ignores keys it doesn't recognize — no warning. A skill that never triggers often has its routing signal sitting in an ignored field. Ignored on skills:
whenToUse (camelCase — the valid field is the snake_case when_to_use), shortname, avatar, exampleQueries. Put trigger phrases in description or the valid when_to_use field, not in an invented key. (Note: when_to_use is valid on skills but NOT on agents — agents fold "when to use" into description with <example> blocks.)
disable-model-invocation: true removes the description from context entirely. The skill can't auto-trigger AND a subagent can't preload it. It becomes usable only by explicit invocation. This skill sets it deliberately — don't flip it expecting auto-routing to start working.user-invocable: false ≠ disable-model-invocation. user-invocable: false hides the skill from the / menu but keeps its description in context so auto-trigger still fires. They control opposite surfaces; setting the wrong one gives the opposite of the intended visibility.- Directory name and
name are separate identities. The on-disk kebab folder name is what wiring/marketplace tooling references; the frontmatter name is the display label. Renaming the directory after release breaks installs; renaming name can break anything that matches on the label. Change neither casually.
- Weak description = dead skill. The most common failure is not a broken body — it's a description that summarizes instead of routing. If Claude never loads the skill, add the literal words a user would type before touching anything else.
- Body narration is recurring cost. Prose like "as models improve…" or "this is powerful because…" stays in context every turn once loaded and pays for nothing. State the action; cut the justification.
- Trust boundary. A skill can instruct Claude to run code and reach the network. Audit any skill from a less-trusted source before installing — read every bundled script and watch for instructions that exfiltrate data or hit untrusted hosts.
Source
Distilled from Anthropic's Agent Skills guidance and this plugin's verified frontmatter research:
