Skip to content

7.2 Anatomy of a Skill

Time to open the hood. A Skill is just a folder with a contract — one required file, a few optional enhancements, and some design rules that separate Skills agents actually use well from Skills that technically exist. Learn the anatomy here; build your own next lesson.

What you will learn

  • Read the structure: SKILL.md, frontmatter, reference files, scripts.
  • Understand progressive disclosure — why Skills are layered the way they are.
  • Apply the design rules that make a Skill reliable rather than decorative.

Builder principle

Write the Skill for a smart stranger with amnesia: assume full intelligence, assume zero shared history. That's exactly what each new session is.

The structure

.claude/skills/
└── newsletter-prep/
    ├── SKILL.md              ← required: the instructions
    ├── voice-examples.md     ← optional: reference material
    ├── checklist.md          ← optional: more reference
    └── scripts/
        └── word_count.py     ← optional: executable helpers

And SKILL.md itself:

---
name: newsletter-prep
description: Prepares weekly newsletter drafts — research, draft,
  social posts. Use when the user asks to prep, draft, or work on
  the newsletter or weekly content.
disable-model-invocation: false
---

# Newsletter Prep

## Process
1. Read docs/content-calendar.md for this week's topic.
2. Read the 2 newest files in published/ — continuity, no repeats.
3. Draft into drafts/YYYY-MM-DD.md following the voice rules below.
4. Run ${CLAUDE_SKILL_DIR}/scripts/word_count.py on the draft —
   target 550–650 words.
5. Draft 3 social posts (formats in checklist.md).
6. Report: what's drafted, what needs judgment, anything off.

## Voice rules
- Match voice-examples.md — rhythm over vocabulary.
- Open with a story or a number. Never "In today's newsletter."
- One idea per issue. Cut the second idea; calendar it instead.

## Hard boundaries
- Never invent statistics or quotes. TODO(owner) for missing facts.
- Never publish — drafts only; publishing is a human decision.

The parts, and why each exists

The frontmatter (name + description) is the catalog entry — the only part always in context (7.1's economics). The description does the heavy lifting: it's how the agent decides this Skill matches the current task. Note its two halves: what the Skill does + when to use it. Skills that never seem to fire almost always have vague descriptions — the agent can't match what isn't stated.

Side-effect control (disable-model-invocation) matters for Skills that deploy, publish, send, commit, purchase, delete, or otherwise cross a consequential seam. Set it to true so only the user can invoke that Skill directly; keep preparation and verification separate from the final side effect. This does not replace permission gates or scoped credentials.

The body of SKILL.md loads when the Skill fires. Structure it like you'd brief that smart stranger: process as numbered steps, standards as rules with reasons, boundaries as hard lines. Everything you learned about instruction-writing in 5.2 applies verbatim.

Reference files hold the bulk — examples, templates, long checklists — and load only when the instructions point to them. This is the third layer of the economics: catalog line (always) → SKILL.md (when relevant) → references (when needed). The pattern has a name, progressive disclosure, and it's the same principle as your CLAUDE.md-links-to-second-brain design from 5.4. Costs scale with relevance at every layer.

Scripts are the sleeper feature: a Skill can carry executable tools. Use ${CLAUDE_SKILL_DIR} when referring to a bundled script so the path resolves regardless of the caller's working directory. Deterministic code can still be wrong or unsafe; review it, constrain inputs, and test success, failure, missing-file, and adversarial-input paths.

The design rules

  1. One skill, one kind of work. "newsletter-prep" is a Skill; "content-stuff" is a landfill. If the description needs "and," split it.
  2. Description = what + when. The matching happens on this sentence. Write it like you're labeling a drawer for someone in a hurry.
  3. Steps read before they write — Skills inherit the loop, always.
  4. Boundaries are part of the capability. "Never publish" isn't a limitation of the Skill — it is the Skill knowing its job ends at drafts. Judgment boundaries from 6.5, packaged.
  5. Reasons ride along. "One idea per issue — multiple competing ideas can split attention" survives novel situations; the bare rule invites clever violations. (5.4's lesson, still true.)
  6. Consequential actions are user-invoked. For deploy/send/publish/commit-style Skills, set disable-model-invocation: true, make the pending action visible, and preserve the human gate.

Read that newsletter Skill again and notice: you already know every ingredient. Process steps (6.5's routine anatomy), voice examples (6.4), boundaries (this whole course), file paths (3.2). A Skill is nothing new — it's everything you've learned, in a folder, with a trigger. That's why it's Chapter 7 and not Chapter 2.

Two notes. First: Skills live at project level (.claude/skills/) or user level (~/.claude/skills/) — same layering as memory and commands; file by scope of the know-how. Second: the scripts folder deserves respect as an interface — a Skill bundling a well-tested script is shipping verified capability, not just guidance. Your data-validation Skill shouldn't describe correct validation; it should carry the validator. Instructions for judgment, executables for invariants.

Try it now

Dissect before you build (surgeons watch first):

  1. Take your starred candidate from 7.1 and sketch its anatomy on paper: what goes in SKILL.md's process vs. rules vs. boundaries? What belongs in reference files? Is there a deterministic step begging to be a script?
  2. Write its full frontmatter description — what + when — in under 40 words.
  3. The layering audit: what's in the catalog line vs. SKILL.md vs. references? Would a stranger with amnesia find what they need when they need it?
  4. Write one success test, one negative test that must not activate the Skill, and one failure-path test. If it can cause an external side effect, set disable-model-invocation: true and test that the agent cannot trigger it opportunistically.

Keep the sketch. Next lesson, it becomes real.

Check your understanding

  • Which part of a Skill is always in context, and what two things must it contain?
  • Explain progressive disclosure across the three layers, in context-budget terms.
  • Why do deterministic steps belong in scripts rather than instructions? (Chapter 2 has the answer.)
  • Which design rule does a Skill named "misc-helpers" violate, and what's the fix?