Anatomy of a skill file

A skill file that works in your head is not the same as a skill file that works in Claude's context window. The difference is structure. This lesson names the parts and explains why each one earns its place.

What this actually is

A skill file has three sections: frontmatter, procedure, and gotchas. That is the full anatomy. Nothing else is required, though some skills add a "prerequisites" section for dependencies. The format is Markdown with YAML frontmatter — human-readable, version-controllable, and parseable without a special parser.

Frontmatter

The frontmatter is metadata that the skill registry (and Claude) read before executing anything. The minimum viable set:

---
name: deploy-website
description: Deploy the marketing site to GitHub Pages from the main branch
author: Seth Shoultes
version: 1.0.0
---

The description field matters more than any other. When Claude loads a skill, the description is what it uses to decide whether this skill applies to the current task. Write it as a single sentence that completes: "This skill is for when you want to…" Then cut the first four words.

Optional fields that add real value:

dependencies: [check-env, run-tests]
triggers: [deploy, ship, go live]

dependencies lists other skills that must be loaded first. triggers are phrases that cause Claude to suggest this skill automatically. Both are hints to the skill loader, not hard constraints.

Procedure

Numbered steps, one action per step, with a success criterion for any step where failure is possible:

## Procedure

1. Confirm you are on the `main` branch: `git branch --show-current` should print `main`
2. Pull latest: `git pull origin main`
3. Run tests: `npm test` — must exit 0
4. Build: `npm run build` — output appears in `dist/`
5. Deploy: `npm run deploy:gh-pages`
6. Verify: open `https://yourname.github.io/yourrepo/` and confirm the page loads

The success criterion in step three ("must exit 0") and step six ("confirm the page loads") are not decoration. They are the checkpoints that tell the agent when to continue and when to stop.

Gotchas

The gotchas section is where the skill earns its value over a simple checklist. It is the "when things go wrong" section — and for an agent, it is the only place where failure handling is explicit:

## Gotchas

- **Deploy fails with "fatal: not a git repository"**: You are not in the project root. Run `git rev-parse --show-toplevel` to find it, then `cd` there.
- **Test failures in step 3**: Do not proceed. Fix the failing tests or stop and report.
- **Page loads but shows old content**: GitHub Pages caches aggressively. Wait two minutes and hard-reload (`Cmd+Shift+R`).

Each gotcha follows the same pattern: the exact symptom, then the exact recovery. Vague gotchas ("if something goes wrong, check the logs") are not useful. The agent cannot act on them.

Why Markdown + YAML

The format is not arbitrary. Markdown is what Claude reads fluently. YAML frontmatter is what skill loaders parse without a schema. The combination means the same file works for human review in a text editor, for skill registry indexing, and for Claude's context window. One file, three uses.

If you get stuck

If Claude ignores the gotchas section: the section header may be missing or misspelled. The parser and Claude both look for ## Gotchas or ## Failure Modes as the section anchor.

If the frontmatter causes a parse error: validate it with python3 -c "import yaml; yaml.safe_load(open('skill.md').read().split('---')[1])". Common culprit is an unquoted colon in the description field.

If a step is ambiguous about who does it (human or agent): add a [human] or [agent] tag at the end of the line. Some procedures have both.

Cross-reference

L5 (The Agent Skills format) covers the extended convention for skills meant for public distribution, including how the registry uses the frontmatter fields you set here.

Deliverable

A skill file with all three sections. The success criterion: paste the frontmatter into a YAML validator and it passes. Read the gotchas aloud — if any of them contain the word "it" without a clear referent, rewrite that gotcha.