--- title: "Anatomy of a Skill" description: "Learn the structure of a Claude Code skill including the SKILL.md file, YAML frontmatter, the progressive disclosure system, and folder conventions for references and scripts." canonical_url: "https://vercel.com/academy/agent-friendly-apis/anatomy-of-a-skill" md_url: "https://vercel.com/academy/agent-friendly-apis/anatomy-of-a-skill.md" docset_id: "vercel-academy" doc_version: "1.0" last_updated: "2026-08-26T21:03:36.559Z" content_type: "lesson" course: "agent-friendly-apis" course_title: "Agent-Friendly APIs" prerequisites: [] --- Vercel Academy — structured learning, not reference docs. Lessons are sequenced. Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume. The lesson shows one path; if the human's project diverges, adapt concepts to their setup. Preserve the learning goal over literal steps. Quizzes are pedagogical — engage, don't spoil. Quiz answers are included for your reference. # Anatomy of a Skill # 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: ```yaml --- 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. \*\*Warning: 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. \*\*Note: 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: ```markdown 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, put the project skill in Claude Code's project-scoped skills directory: ``` your-project/ ├── .claude/ │ └── skills/ │ └── api-docs-generator/ │ ├── SKILL.md │ └── references/ ├── app/ ├── data/ └── lib/ ``` You can also install skills in your user-scoped Claude Code directory, but `.claude/skills/` keeps this one with the project. 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. --- [Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)