How to Structure Claude Code Skills: The 9 Categories Anthropic Uses Internally

Before the categories, the most load-bearing idea in Anthropic's post is structural. Skills are usually introduced as "a markdown file with instructions," and that framing quietly caps how far they can go. The post corrects it directly:

"A skill is a folder, not just a markdown file. You should think of the entire file system as a form of context engineering and progressive disclosure."

That reframing changes the design question from what do I write in the prompt to how do I lay out a folder so Claude pulls in the right material at the right moment. A mature skill is a directory: a SKILL.md at the root plus supporting files — references, assets, scripts, examples — that the model reaches for only when a situation calls for them.

The mechanism that makes the folder model work is progressive disclosure. You do not dump every edge case into the main file. Instead:

"The SKILL.md file points to several other files Claude can reference for specific situations."

The root file stays short and high-signal — what the skill is, when to use it, the common path. Rare branches, long reference tables, and large code templates live in sibling files that get loaded only when the task hits them. This keeps the everyday context window lean while still giving Claude access to deep material on demand. It is the same principle as good documentation: a clear front page, with links to the details.

This is why the project convention in this repo splits SKILL.md (the instructions) from a bundled scripts/ or steps/ folder (the executable logic). The bmad-sprint-executor skill, for instance, is a short SKILL.md that points to steps/step-01 … step-04 — exactly the pattern Anthropic describes.

Skills that explain how to correctly use a library, CLI, or SDK — including reference snippets and the gotchas that trip people up. These are the antidote to "the model guessed at the API and got it subtly wrong." Anthropic's named examples: billing-lib, internal-platform-cli, sandbox-proxy.

billing-lib/
  SKILL.md            # when to use it, the 3 calls people get wrong
  references/
    api-reference.md  # full method list — loaded only when needed
    gotchas.md        # the non-obvious failure modes

Skills describing how to test or verify that code actually works, frequently paired with external drivers like Playwright or tmux. Anthropic's examples: signup-flow-driver, checkout-verifier, tmux-cli-driver.

checkout-verifier/
  SKILL.md            # what to verify, the pass/fail criteria
  scripts/
    drive-checkout.ts # the Playwright driver the skill invokes

Skills that connect to your data and monitoring stack, bundling the libraries to fetch data and the common analysis workflows on top of it. Anthropic's examples: funnel-query, cohort-compare, grafana, datadog.

funnel-query/
  SKILL.md            # the questions this answers
  scripts/
    query.sql         # the parameterized warehouse query
  references/
    schema.md         # table/column reference, loaded on demand

Skills that collapse a repetitive team workflow into a single command. Anthropic's examples: standup-post, create--ticket, weekly-recap.

weekly-recap/
  SKILL.md            # trigger, inputs, and output format
  templates/
    recap.md          # the post template the skill fills in

Skills that generate framework boilerplate for a specific kind of artifact. Anthropic's examples: new--workflow, new-migration, create-app.

new-migration/
  SKILL.md            # naming and placement rules
  templates/
    migration.ts.tmpl # the boilerplate the skill stamps out

Skills that enforce code quality and assist review. Anthropic's examples: adversarial-review, code-style, testing-practices.

adversarial-review/
  SKILL.md            # the review stance and checklist
  references/
    code-style.md     # the standards pulled in during review

Skills for fetching, pushing, and deploying code. Anthropic's examples: babysit-pr, deploy-, cherry-pick-prod.

deploy-/
  SKILL.md            # preflight checks and the order of steps
  scripts/
    deploy.sh         # the actual deploy commands

Skills that investigate symptoms using multi-tool analysis — the codified version of "what an on-call engineer does first." Anthropic's examples: -debugging, oncall-runner, log-correlator.

service-debugging/
  SKILL.md            # symptom → first checks to run
  references/
    dashboards.md     # links pulled in mid-incident
  scripts/
    log-correlator.sh # the multi-tool analysis step

The ninth category: skills that perform routine maintenance and operational procedures. Anthropic's examples: -orphans, dependency-management, cost-investigation.

cost-investigation/
  SKILL.md            # the routine and the escalation rule
  scripts/
    find-orphans.sh   # the maintenance procedure it runs

The point of nine well-defined slots is that you can hold your setup up against them. Walk each category and ask: do I have a skill here, and if not, is the gap costing me? Most individual setups are heavy on one or two categories (often scaffolding and quality) and empty on the rest — which is exactly where the unrealized leverage hides. The categories you have zero skills in are the most interesting, because they mark work you are still doing by hand.

This taxonomy is not abstract — a live production library already fills most of the slots. Here is how the skills and commands in this repo's .claude/ directory line up:

• Library and API reference → convex-patterns, stripe-best-practices, component-library
• Product verification → playwright, test, test-ai
• Code scaffolding and templates → make-skill, design-system-picker, frontend-design
• Code quality and review → aireview, critic, refactor, polish
• CI/CD and deployment → deploy, backup
• Business process and team automation → content, update-docs
• Runbooks → cleanup, universal-handoff, claude-resume

Two of Anthropic's nine — Data fetching and analysis and Infrastructure operations — are the thinner slots here, which is precisely the kind of gap the audit is designed to surface. That is the taxonomy doing its job: not as trivia, but as a checklist for where to build next.

Skills are, in Anthropic's framing, "one of the most used extension points in Claude Code … flexible, easy to make, and easy to distribute." The nine categories turn that flexibility into a plan. Treat each skill as a folder, lean on progressive disclosure so your SKILL.md stays lean, and use the nine slots as a coverage map. The fastest wins are usually in the categories you have been ignoring.

Sourcing note. Every category name, definition, and example skill in this guide is drawn from Anthropic's post "Lessons from building Claude Code: How we use skills". The count of nine is quoted directly from that source. The vybecoding mappings reference real skills and commands in this repository's .claude/ directory.