Anatomy of a Skill

We just spent a full lesson writing documentation by hand, and I owe you an apology for that. It works, but it's manual. Every time the API changes, someone has to update those docs strings and make sure they still match.

What if Claude could do it for you? (It can.)

A Claude Code skill is a set of instructions, packaged as a folder, that teaches Claude how to handle a specific task. Instead of re-explaining your preferences, processes, and domain knowledge in every conversation, you teach Claude once. It applies that knowledge every time.

We're going to build a skill that reads your API code and generates the agent-friendly markdown docs automatically.

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

That's it. No package.json, no build step, no runtime. A skill is just structured markdown that Claude reads.

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 — kebab-case, should match the folder name.

description — This is the most important field. It tells Claude two things: what the skill does, and when to use it. Include specific trigger phrases that a user might say. Without good triggers, the skill won't activate when needed.

Progressive disclosure

Skills use a three-level system to minimize token usage:

1. Frontmatter (always loaded) — Claude reads the name and description to decide if the skill is relevant. This is cheap.
2. SKILL.md body (loaded when relevant) — If Claude decides the skill matches the current task, it loads the full instructions. This is the main content.
3. Referenced files (loaded on demand) — Files in references/ that Claude can pull in when it needs deeper context. Like our doc-patterns.md file.

This matters because context is finite. A skill with 10,000 words of instructions loaded into every conversation would waste tokens. Progressive disclosure means the full instructions only appear when Claude needs them.

The references folder

Our skill will have one reference file: doc-patterns.md. This contains the formatting rules for agent-friendly documentation (tables for parameters, curl examples, error case format). We're putting it in references/ instead of the SKILL.md body because it's supporting detail, not core instructions.

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.

That's the full anatomy: a folder, a SKILL.md with frontmatter and instructions, and optional references for supporting detail. The structure is simple on purpose. The real work is writing instructions specific enough that Claude can follow them without guessing. We'll do exactly that in the next lesson.

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.