Vercel Logo

Anatomy of a Skill

The documentation from Section 2 works, but every API change requires someone to update the strings and verify them again.

A skill can automate that work.

A Claude Code skill packages instructions for a specific task in a folder. It makes the same process and domain knowledge available whenever the task comes up.

You'll build a skill that reads the API code and generates Markdown documentation.

Outcome

Understand the file structure, frontmatter format, and progressive disclosure system of Claude Code skills.

Fast Track

  1. A skill is a folder with a SKILL.md file. That file is the entire skill definition.
  2. YAML frontmatter in SKILL.md decides when the skill loads. The description field contains trigger phrases Claude matches against.
  3. Files in references/ load on demand, giving Claude deeper context without bloating the initial token cost.

The folder

A skill is a folder containing at minimum one file: SKILL.md. The folder name must be kebab-case. No spaces, no underscores, no capitals.

api-docs-generator/
├── SKILL.md              # Required: the main instruction file
└── references/           # Optional: supporting docs Claude can pull in
    └── doc-patterns.md

A skill needs no package.json, build step, or runtime. Claude reads the structured Markdown directly.

The folder can also include scripts/ for executable code and assets/ for templates, but we won't need those for this skill.

SKILL.md

The SKILL.md file has two parts: YAML frontmatter and the instructions body.

Frontmatter is how Claude decides whether to load the skill. It's always read, even when the skill isn't active:

---
name: api-docs-generator
description: Generates agent-friendly markdown documentation for API routes. Use when user says "generate docs", "document this API", "create API documentation", or "make docs for my endpoints".
---

Two fields matter here:

name: Use kebab-case and match the folder name.

description: State what the skill does and when to use it. Include phrases a user might use when requesting the task so Claude can match the skill to the request.

SKILL.md is case-sensitive

The file must be exactly SKILL.md. Not skill.md, not Skill.md, not SKILL.MD. Claude won't find it otherwise.

What if Claude doesn't trigger your skill?

Claude matches the user's message against the description field. If your skill never activates, the problem is almost always missing trigger phrases. Add the exact words your users would say: "generate docs", "document this API", "create API documentation". The more variations you include, the more reliably the skill fires.

Progressive disclosure

Skills load information in three stages:

  1. Frontmatter (always loaded): Claude reads name and description to decide whether the skill is relevant.
  2. SKILL.md body (loaded when relevant): Claude loads the full instructions after matching the skill to the task.
  3. Referenced files (loaded on demand): Claude reads files such as doc-patterns.md when a step requires deeper context.

Progressive disclosure keeps unnecessary detail out of the initial context. Full instructions and references load only when the task needs them.

The references folder

Our skill uses doc-patterns.md for parameter tables, curl examples, and error formatting. It belongs in references/ because those formatting rules support the main workflow.

In the SKILL.md body, we'll point to it:

Consult `references/doc-patterns.md` for the formatting rules.

Claude will read that file when it gets to that step.

Where skills live

For this course, we'll put the skill folder in the project root:

your-project/
├── api-docs-generator/    # The skill
│   ├── SKILL.md
│   └── references/
├── app/
├── data/
└── lib/

You can also install skills globally in your Claude Code settings, but keeping it in the project makes it portable. Anyone who clones the repo gets the skill.

A skill combines a SKILL.md file with optional references. The next lesson focuses on writing instructions specific enough for Claude to follow without guessing.

Try It

No code to run in this lesson. The folder structure comes together in 3.2 when you build the skill.

Commit

No code changes to commit.

Done-When

  • You can explain the three levels of progressive disclosure (frontmatter, body, references)
  • You know that SKILL.md is case-sensitive and must be exactly that name
  • You can describe what the description field does and why trigger phrases matter
  • You understand the folder structure: SKILL.md at root, optional references/, scripts/, assets/

Solution

No code solution for this lesson. The structure you learned here is what you'll build in 3.2.

Was this helpful?

supported.