SKILL.md Explained: Every Frontmatter Field and Progressive Disclosure

SKILL.md is the whole contract. Everything the agent knows about when to fire, what to load, and what tools it may touch comes from one file. Get the structure wrong and the skill either never triggers or triggers on everything.

If you have not built a skill before, start with the guide to creating Claude Code skills. That piece covers the build-or-not decision, the distillation process, and how the architecture compares to a plain prompt. This article is the technical reference beneath it: every frontmatter field, what it does, when it matters, and the three-level progressive disclosure model that keeps context cost proportional to task complexity.

The file lives at .agents/skills/<your-skill-name>/SKILL.md. That path is required. Add references/, scripts/, or assets/ alongside it when the skill needs supporting material. Everything in the skill’s behavior is anchored to SKILL.md.

What SKILL.md is

SKILL.md is the entry file for every Claude Code skill. It has two parts: a YAML frontmatter block that controls how the skill is discovered, triggered, and constrained, and a Markdown body that is the actual prompt (the persona, the output format, the loading map, the constraints). The frontmatter is machine-readable configuration; the body is executable instruction.

The split matters because the two parts load at different times. The name and description fields sit in the skill-listing layer that Claude reads every session, before any skill activates. They cost context always. The body loads only when the skill triggers. Reference files load only when the body explicitly tells the agent to read them. Three tiers, each costing context only when earned.

The frontmatter table below covers every field. The FileTree shows the directory convention. The LayerStack maps the three disclosure tiers. Read the frontmatter first: it determines what loads, when, and at what capability level.

Every frontmatter field

The description field is the primary trigger mechanism, not the name, not the slash command. Claude reads descriptions to decide which skill matches the user’s request. Everything else in the frontmatter configures the execution environment or narrows which invocations qualify: permissions, model, effort level, context isolation. The table below covers every field Anthropic documents.

SKILL.md frontmatter reference

name and description are the only universally required fields. The rest are scoping and configuration: use them to make the skill's permissions explicit, not inherited.

Field	Required	Values / Type	Notes
name	yes	string	Becomes the slash command /name. Lowercase, hyphens. Also the activation coordinate: the more specific the name, the denser the model's cluster.
description	yes	string	Primary trigger mechanism. Combined with when_to_use, capped at ~1,536 chars in the listing. Write to match user intent, not to summarize the skill. Lean pushy.
when_to_use	no	string	Supplements description with explicit activation scenarios. Shares the ~1,536 char budget. Use for edge cases and specific conditions the description does not surface.
argument-hint	no	string	Shown in slash-command autocomplete. e.g. 'offer to evaluate' or 'PR to review'. Keeps the interface self-documenting.
arguments	no	object	Typed parameter definitions for structured invocation. Useful when arguments control branching inside the body, e.g. a mode: quick | deep switch.
user-invocable	no	boolean	Default true. Set false to make the skill model-only: the agent can invoke it as a sub-step, but it will not appear in the user-facing slash menu.
disable-model-invocation	no	boolean	Prevents the model from self-invoking the skill. Pair with user-invocable: false for fully manual control. The skill fires only when the user explicitly calls it.
allowed-tools	no	list	Allowlist of tools this skill may use. Overrides the session default. Omit to inherit all session tools, which is usually too permissive for a specialized skill.
disallowed-tools	no	list	Blocklist for specific tools. Use to prevent Bash, Edit, or Write from a skill that should only read. Turns an accidental misfire into a hard boundary.
model	no	string	Override the model for this skill. Run quick-lookup skills on a smaller, faster model. Run deep-analysis skills on the most capable one. Cost control belongs in config.
effort	no	low | medium | high | xhigh | max	Sets the thinking level. high or xhigh for security audits and complex analysis; low for formatters and quick lookups. max only when you genuinely need the deepest reasoning.
context	no	fork	Run the skill in an isolated context fork, separate from the main conversation. Use for skills that do substantial work before returning an answer. Prevents long sessions from consuming the conversation's context window.
agent	no	string	Delegate invocation to a named sub-agent. Enables multi-agent architectures from a single SKILL.md entry point.
hooks	no	object	Pre- and post-invocation hooks. Run setup scripts, environment validation, or cleanup around skill execution without embedding that logic in the body.
paths	no	list	Restrict file access to specific directories. A code-review skill for one service does not need access to the whole monorepo. Narrow this as far as the task allows.
shell	no	boolean	Explicitly enable or disable shell command access for this skill. Make the permission visible in the file rather than inherited from the session context.

Here is a working frontmatter block for a security review skill. Notice the disallowed-tools list: a review skill that cannot write files cannot accidentally apply a fix, which makes the contract explicit rather than relying on the model’s judgment:

---
name: security-reviewer
description: >
  Reviews code for security vulnerabilities, injection risks, authentication
  gaps, and secrets exposure. Applies OWASP Top 10 as the base checklist.
  INVOKE for any PR touching auth, database queries, file I/O, API endpoints,
  or environment variable handling. Do not invoke for unrelated refactors.
  REQUIRED: read references/00-checklist.md before responding.
when_to_use: >
  Invoke for PRs touching authentication, authorization, input sanitization,
  secrets handling, or third-party dependency additions. Also useful before
  any deployment that changes the attack surface.
effort: high
allowed-tools: [Read, Grep, Glob]
disallowed-tools: [Bash, Edit, Write]
context: fork
---

The description front-loads the trigger pattern (“auth, database queries, file I/O, API endpoints”) so the model sees the matching signal immediately, before the description is truncated.

Directory layout

A skill directory has one required file and three optional subdirectories. Every skill follows the same layout, which means tools, CI scripts, and other skills can reason about structure without inspecting every file individually.

.agents/skills/
└── security-reviewer/
    ├── SKILL.md              ← required entry file
    ├── references/
    │   ├── 00-checklist.md   ← decision checklist
    │   ├── 01-owasp-top10.md ← framework reference
    │   └── 02-examples.md    ← worked examples and anti-patterns
    ├── scripts/
    │   └── validate.sh       ← executable pre-check
    └── assets/
        └── report-template.md ← output template

Skill directory layout

• security-reviewer/skill root
  • SKILL.mdrequiredfrontmatter + prompt body + loading map
  • references/loaded on demand by instructions in SKILL.md body
    • 00-checklist.mdalways loaded: decision checklist
    • 01-owasp-top10.mdframework reference
    • 02-examples.mdworked examples and anti-patterns
  • scripts/executable code the skill can run
    • validate.shenvironment pre-check
  • assets/files used in output: templates, icons, data
    • report-template.mdoutput scaffold

The references/ directory is where most of the leverage is. A skill with no references answers from the model’s weights alone. That is the same as having no skill. The SKILL.md body tells the agent which files to read and when. Nothing in references/ loads automatically. That constraint is the architecture, not a limitation.

Progressive disclosure: three levels

Progressive disclosure keeps skills fast. The model loads only what the current task demands. Each level adds context only when triggered.

Progressive disclosure: three levels

1. L1

   Metadata: always in context

   name and description (and when_to_use) sit in the skill listing the model reads every session, before any skill activates. This is the trigger layer: roughly 100 words per skill, always in context. Every word costs. Front-load the signal: the strongest match for user intent belongs in the first sentence, not the third.

   name: alex-hormozi-offer-design
   description: >
     Evaluates offers, pricing, guarantees, and value stacks using
     Hormozi's frameworks (Value Equation, Grand Slam Offer, RAISE).
     INVOKE for any question about pricing strategy, risk reversal,
     guarantee design, or offer testing. Do not use for brand/content work.

   +
2. L2

   Skill body: loads on trigger

   The Markdown body of SKILL.md loads when the skill activates. This is the main prompt: persona, output format, constraints, and the loading map that routes the agent to references. Keep the body under ~500 lines. If it grows past that, the body has become a reference. Move the excess to references/ and add a loading instruction.

   +
3. L3

   Reference files: load as needed

   Files under references/ load only when the SKILL.md body explicitly instructs the agent to read them. The model decides. Nothing auto-loads. This is the critical point: without an explicit loading map in the body, the agent skips the references entirely and answers from training weights. Your distilled knowledge sits unread.

The loading map connects the skill body to the reference files and removes the ambiguity that lets the model take shortcuts:

## When to load references

| Question type            | Load this file                      |
| ------------------------ | ----------------------------------- |
| Any offer evaluation     | references/00-canon.md (always)     |
| Pricing or risk reversal | references/04-pricing.md            |
| Offer construction       | references/02-grand-slam-offer.md   |
| Objections or close rate | references/07-closing-and-sales.md  |
| Final verdict            | references/11-decision-checklist.md |

Explicit beats polite. “Consult the references” is a suggestion. A table that says “price question loads pricing.md” is an instruction. The model follows the second more reliably than the first.

Writing descriptions that trigger

Descriptions are the primary trigger mechanism, not the name, not the slash command. Claude reads descriptions to decide which skill matches the user’s request. A description that reads like a marketing summary is functionally broken. It describes the skill accurately and matches no real user intent.

Descriptions that undertrigger sound like elevator pitches: “A skill for reviewing code security.” Descriptions that trigger look like the pattern they are meant to catch: “Reviews pull requests for injection vulnerabilities, authentication gaps, secrets exposure, and broken access control. Invoke for any PR touching auth, database queries, environment variables, or third-party dependency additions.”

The difference is specificity of intent, not length. The second description matches what a developer would type or say when they need the skill (the vocabulary of the problem, not the vocabulary of the solution).

Anthropic’s own guidance is to make descriptions “slightly pushy” because skills tend to undertrigger in practice. The cost of a false positive (the skill fires when it should not) is lower than the cost of consistent undertriggering, where the skill never fires at all. Lean toward over-specification, not summary.

Reference files need a table of contents above 300 lines

Any reference file over 300 lines needs a table of contents at the top. This is structural, not stylistic.

When the agent loads a reference file, it reads from the top. A long file without a TOC means the model scans structure before finding the relevant section: wasted tokens and degraded accuracy. A TOC at the top lets the agent jump directly to the anchor the task needs, which matters most for multi-domain references that handle several different question types.

The rule also exposes a design smell: if a single reference file is over 300 lines and does not have obvious chapters, it probably covers too many decision domains. Split it. My offer evaluation skill has 13 reference files, most under 100 lines each, split by decision: pricing, guarantees, value equation, closing, retention. The canon file (which loads on every invocation) has a TOC. Everything else is short enough to read in full without one.

Design the loading map in SKILL.md and the references/ structure together. If the body says “for pricing questions, load references/04-pricing.md,” that file should be focused enough that the agent can read it completely in a single pass. Brevity in references is a feature: it keeps L3 cheap.

To verify that your skill triggers correctly and uses the references you wrote, see the guide to testing Claude Code skills. For real skill structures to study (including the alex-hormozi-offer-design skill with 13 decision-split references), see Claude skill examples. If you are still deciding whether to build a skill at all, start with the guide to creating Claude Code skills.

What is the minimum viable SKILL.md?+

name and description are the only required fields. A skill with just those two will trigger and execute. Without allowed-tools or disallowed-tools, it inherits the full session permission set, which is usually too permissive for a specialized skill.

The practical minimum for production: name, description, effort, and at least one of allowed-tools or disallowed-tools to make permissions explicit rather than inherited.

Does description or when_to_use trigger the skill?+

Both contribute. The model reads both when scanning the skill listing to match the current request. They share a combined character budget of roughly 1,536 characters.

Use description for the primary intent pattern (the vocabulary of the problem the skill solves). Use when_to_use for specific scenarios and edge cases the description does not surface.

Do reference files load automatically when the skill activates?+

No. Nothing in references/ loads automatically.

The SKILL.md body loads on activation. Reference files load only when the body's instructions tell the agent to read a specific file. Without an explicit loading map in the body, the agent skips the references and answers from training weights. Your distilled knowledge is unreachable.

What does context: fork do?+

It runs the skill in an isolated context, separate from the main conversation. This prevents long skill sessions (deep analysis, multi-step research, extensive reference loading) from consuming the context window of the conversation that invoked the skill.

Use it for skills that do substantial work before returning an answer. For quick lookups and formatters, the overhead is not worth it.

Should effort: max be the default?+

No. Effort scales thinking time and cost. Set it to what the task actually requires: low for quick lookups and formatters, high for security audits and complex analysis, max only when you genuinely need the deepest reasoning.

Effort: max on a simple formatting skill wastes compute. Effort: low on a security audit will miss things. Match the effort to the decision weight, not to a desire for safety.

Can a skill invoke another skill?+

Yes: via the agent field or by including invocation instructions in the body. A router skill can delegate to specialized sub-skills depending on the input type.

Composition happens at the orchestration layer: one skill hands off to another, returns its output, and the next skill picks it up. Two skills do not run simultaneously inside one SKILL.md body.

How long should the SKILL.md body be?+

Under 500 lines. If the body grows past that, it has become a reference. Move the excess to references/ and add a loading instruction that points to it.

The body is the router and prompt. The references are the knowledge. Keeping them separate keeps activation fast: the full body loads on every invocation, so every line there costs context on every call.

Where does the skill directory live?+

At .agents/skills/<your-skill-name>/. The SKILL.md file is the required entry point at that path. Subdirectories (references/, scripts/, assets/) are optional and follow the convention documented in this article.

The consistent path lets other tools, CI pipelines, and skills discover and reason about your skill library without reading every file.