Learning objectives

By the end of this chapter, you will be able to:

1. Explain what an agent skill is — a folder containing a `SKILL.md` (Markdown + YAML frontmatter) plus optional scripts and resources that packages a reusable, consistent workflow Claude can auto-invoke when a skill's `description` matches the conversation — and why that's *packaging*, not a new kind of intelligence.
2. Describe progressive disclosure in depth — at session start Claude sees only a cheap *listing* of each skill (its name + `description`); the full `SKILL.md` body loads only when the skill is selected (and then stays in the conversation for the rest of the session); bundled files/scripts load only when referenced — and explain that Claude decides *which* skill to apply from that listing (primarily the `description`, with `when_to_use` appended; the body's first paragraph is used only if `description` is omitted), so workflow text deeper in the body normally has no effect on *when* the skill fires.
3. Build a custom project-level skill at `.claude/skills/<name>/SKILL.md` with a bundled script, write a `description` that triggers it, and recognize that a skill is a packaging mechanism that can contain deterministic scripts, AI calls, or both — so a skill does not by itself make a workflow 'AI-driven.'
4. Compose deterministic execution with AI by having a skill's script invoke the Claude CLI (`claude -p`), and explain that recovery is *possible but not guaranteed* — because a skill injects instructions rather than binding to exact paths, Claude can often reason around a moved script or fall back to its own approach, but a skill is not a deterministic enforcement mechanism (for that, use hooks or scripts outside the prompt-instruction layer).
5. Place skills among the other agent primitives — Skills vs MCP vs subagents vs slash commands — across context loading, trigger, execution location, isolation, and context efficiency, and apply the rule of thumb (recurring methodology/expertise in the main context → skill; heavy work that would bloat the main context → subagent; external systems/data → MCP), noting that custom slash commands are now merged into skills and that skills are a cross-product open standard.

Before we start — skills, "primitives," progressive disclosure, and the CLI

Skim this if you already worked through Chapter 3's Skills section and you're comfortable with what a context window is, what a primitive means here, and what claude -p does. If any of that is fuzzy, read it first.

You've met skills already — this chapter goes underneath. Chapter 3 introduced Skills as the modern form of custom slash commands: a SKILL.md file with YAML frontmatter, where the body is a prompt Claude runs and the frontmatter configures it. That was the mechanics — how to make one. This chapter is the architecture: what a skill really is, how it spends (or saves) your context window, how it can run real scripts, and how it compares to the other tools in the box. If "progressive disclosure," "allowed-tools is a grant," and .claude/skills/<name>/SKILL.md already ring a bell, you're ready.

A skill, in one sentence. A skill is a folder containing a SKILL.md (instructions) plus optional scripts and resource files, that packages a reusable workflow so the agent performs a recurring task consistently — and that Claude can pull in on demand when the task is relevant. The official framing calls skills "procedural knowledge containers." The word that matters is consistency: you package a workflow once, and the agent does it the same way every time, for everyone on the team.

"Primitive." Throughout this chapter (and the book) a primitive just means one of the basic building blocks you assemble agent behavior from. You've now met four: Skills (this chapter), MCP (Chapter 4 — connecting to external tools/data), subagents (Chapter 7 — delegating to an isolated helper), and slash commands (the /name you type). The last section compares them head to head.

The context window, again. Same idea as Chapter 7: the model's working memory is finite, and every instruction you load into it competes for the model's attention. The whole point of skills is to keep that window lean — to load a skill's detailed instructions only when they're needed, rather than carrying them on every turn.

Progressive disclosure. This is the chapter's core idea and we'll define it carefully in §2. The one-line version: Claude sees a cheap summary of every skill all the time, but loads a skill's full contents only when it decides the skill is relevant — and a skill's bundled files only when it actually uses them. Like a manual that opens with a table of contents.

claude -p (the CLI in "prompt mode"). Claude Code is also a command-line program. Running claude -p "some prompt" sends that one prompt, prints Claude's answer to standard output, and exits — no interactive session. It's the headless mode you met in Chapter 5 (the GitHub Action) and Chapter 7. It matters here because, in §4, a skill's script calls claude -p to generate text — an AI call nested inside a deterministic workflow.

How to read this chapter. Each numbered section ends with an > Analogy — … box that restates the idea in plain language. Lean on them or skim them as you like.

Why this chapter matters

By now you can extend Claude Code in several ways, and it's easy to reach for the wrong one. Drop a design system into CLAUDE.md and it rides along on every prompt — including the backend tasks where it's irrelevant — quietly eating context and degrading answers. Stand up an MCP server for a job that's really just "follow these five steps" and you've added a network dependency for something a text file could do. The skill that this chapter is about is the tool for a specific, common shape: a recurring procedure you want the agent to perform consistently, loaded only when it's relevant.

The reason skills are worth a whole chapter — and not just the Chapter 3 mechanics — is progressive disclosure. It's what lets you keep dozens of skills lying around a project for almost no context cost, and it's the property that distinguishes skills from the older "stuff everything into the prompt" approach. Understand progressive disclosure and you understand why skills scale.

The chapter builds in three moves, and so does this lesson. First, what a skill is — by watching the same styling task done two ways, by prompt and by skill. Then, what skills can do — bundling real scripts, composing deterministic execution with AI calls, and recovering gracefully when things break. Finally, where skills sit — a clear-eyed comparison with MCP, subagents, and slash commands, so you reach for the right primitive every time. Throughout, the honest through-line: a skill is packaging, not magic. It makes the agent reliably good at one thing; it doesn't make it smarter.

A note on currency. Skills are recent and moved fast. They were introduced in Claude Code during 2025 (the book dates this to late 2025) and were later published as a cross-product open standard at agentskills.io — so the same SKILL.md now travels beyond Claude Code to the Claude apps and the API / Agent SDK. The book's examples are Claude Code, which is exactly right for us; just know skills reach further than the chapter shows. Treat launch dates and ecosystem framing as background context (from the announcement and the open standard), not as Claude Code behavior — and verify behavior specifics against code.claude.com/docs/en/skills.

Lesson

1. What a skill really is — a folder, not a feature

Start with the shape on disk, because it explains everything else. A skill is a directory whose required member is a single SKILL.md file:

.claude/skills/git-pushing/
├── SKILL.md                 # required: frontmatter + instructions
└── scripts/
    └── smart_commit.sh       # optional: bundled script the skill can run

SKILL.md is Markdown with a YAML frontmatter block, exactly like the subagent and skill files you've seen. Here is the frontmatter of the chapter's worked example — a git-pushing skill (adapted from a community skills marketplace) that stages, commits, and pushes with a conventional commit message:

---
name: git-pushing
description: >
  Stage, commit, and push git changes with conventional commit messages.
  Use when the user wants to commit and push changes, mentions pushing to
  remote, or asks to save their work. Also activates when the user says
  "push changes", "commit and push", "push this", or "push to github".
---
# Git Push Workflow
Stage all changes, create a conventional commit, and push to the remote branch.

## Workflow
Always run the bundled script rather than manual git commands:

bash ${CLAUDE_SKILL_DIR}/scripts/smart_commit.sh "feat: add feature"

Two things are already doing a lot of work here. The description is the most important line in the file — it's what Claude reads to decide when this skill applies (§2). And the body expresses an opinionated workflow: it tells Claude to run the bundled script rather than improvise git commands. That's the essence of a skill — consistency: if your team wants every commit to follow a specific structure, you package that intent into a skill so the agent is guided to do it the same way each time. (Important nuance for §3–§4: this is an instruction Claude usually follows, not a hard guarantee — for behavior that must happen deterministically, you'd reach for a hook, not a skill.) Note the script path uses ${CLAUDE_SKILL_DIR} — the current, portable way to point at a bundled file: it resolves to the directory holding this SKILL.md regardless of where the skill is installed (personal, project, or plugin) and regardless of the working directory. (The book writes a hard relative path like skills/git-pushing/scripts/…, which is brittle; prefer the variable.)

Skills are folders, not just files — they can bundle scripts, executables, and resource files alongside SKILL.md. The brand-styling example the book opens with is a brand-guidelines skill (from the official anthropics/skills repo) whose SKILL.md carries the design system — colors, typography, voice — and whose extra files hold the detail.

The prompt-vs-skill contrast. The book makes "what is a skill for" concrete by styling the recurring HookHub demo app two ways:

• Without a skill (Scenario 1). You prompt Claude directly — "make this look like the Anthropic brand" — and it does a good job, fetching and re-deriving the design language live. But every time you do it, it re-derives the same context from scratch. The tempting fix — paste the design system into CLAUDE.md — backfires: now that context attaches to every prompt, including backend work where it's useless, expanding context and degrading answers.
• With a skill (Scenario 2). You package the design language as a brand-guidelines skill. Now, when (and only when) the work calls for it, Claude recognizes the skill is relevant and loads its design context — conditionally, when the task matches, rather than globally on every prompt. (Once loaded, that content does stay in the session — so you keep a skill's body lean; see §2 — but you've avoided paying for it on the backend tasks where it was never relevant.)

That contrast is the whole value proposition: a skill is the place to put recurring procedural knowledge so it's available without being always-on.

Analogy — the recipe card in the kitchen drawer A skill is a recipe card in the kitchen's drawer. It's written once, in a fixed format, so that whoever is on shift makes the dish the same way (consistency). It isn't always on the counter cluttering your workspace — you pull it out when that dish is ordered, follow it, and put it back. And it's just a card: it doesn't make the cook more talented, it makes them reliable at this one dish. A skill is packaging, not a promotion.

2. Progressive disclosure — why a hundred skills cost almost nothing

Here is the property that makes skills scale, and the heart of the chapter. Progressive disclosure is a three-stage loading model:

1. **At session start — the skill listing only.** Claude loads just a short listing of every available skill: its name and description (with when_to_use appended). This is a small, fixed cost per skill — far less than the skill's full body — regardless of how big or complex the skill is internally, so a project can keep many skills available for very little upfront context. (The listing is capped per skill and the overall budget is configurable; the docs cover the exact limits.)
2. When a skill is selected — the full SKILL.md body loads. Claude compares your request against the skill listing; if one matches (or you invoke it with /name), then the rest of that file — the workflow, the instructions, the script references — loads into context. Once loaded, that content stays in the conversation for the rest of the session (Claude doesn't re-read the file each turn), so it's a recurring token cost — which is exactly why you keep a SKILL.md body lean and push detail into bundled files. (When the context later compacts, Claude Code re-attaches the most recent invocation of each skill within a budget, so heavily-used sessions can drop older skills — re-invoke one if it seems to fade.)
3. When the skill references a bundled file — it loads on demand. If a skill ships five scripts and the agent uses one, only that one enters context. Unused files cost nothing.

The payoff, in the docs' words: detailed reference material "costs almost nothing until you need it." This is the same context-economy principle behind Chapter 7's subagents and Chapter 4's MCP tool-search — load detail lazily, keep the working window lean.

**The sharpest demonstration: editing the deep body doesn't change when the skill fires.** The book runs a deliberately surprising experiment. The git-pushing skill has a ## When to Use section in its body (below the frontmatter) listing trigger phrases. The author adds a new phrase — "push to remote" — to that section, clears the session, and types "push to remote." The skill still fires… but not because of the edit. It fires because "push to remote" is semantically close to phrases already in the description. The deep body edit didn't participate in the selection decision:

**Claude decides which skill to apply from the skill listing — primarily the description.** It matches your intent against each skill's listing (the description, with the optional when_to_use field appended). Arbitrary workflow text deeper in the body isn't part of the listing — it loads after the skill is chosen — so it normally has no effect on selection. (The one exception: if you omit description entirely, Claude falls back to the first paragraph of the Markdown body as the listing text.) So if a skill isn't firing when it should, fix the description (or add when_to_use), not the workflow text further down.

This is progressive disclosure made tangible: the listing is the always-loaded "table of contents" the agent routes on; the body is the chapter it opens only after deciding to read.

Analogy — the library with a card catalog A skill library works like a reference library. You don't photocopy every book onto your desk "just in case" — your desk would be buried (that's CLAUDE.md with everything in it). Instead, a card catalog sits by the door: one index card per book, with the title and a one-line summary (the name + description). You scan the cards for free, pull the one book you need off the shelf (the SKILL.md body), and open only the chapter that's relevant (a bundled file). A hundred books cost you a hundred index cards' worth of glance — the shelves stay off your desk until you reach for them.

3. A skill that does real work — bundling scripts

A skill isn't limited to feeding Claude reference text. It can carry scripts the agent executes, turning a skill into a packaged, runnable workflow. The git-pushing skill's body points at one:

bash ${CLAUDE_SKILL_DIR}/scripts/smart_commit.sh "feat: add feature"

smart_commit.sh lives in the skill's scripts/ folder and does the real git work — staging, building a conventional commit message, adding a footer, pushing with -u. (${CLAUDE_SKILL_DIR} resolves to the skill's own directory wherever it's installed — the portable way to reference a bundled file.) Two details matter:

• The agent only learns about the script after it selects the skill. The script reference is in the body, so — by progressive disclosure — it enters context only once git-pushing is chosen. Until then, the agent doesn't even know the script exists.
• **The skill guides the agent toward the script over improvising.** The body's instruction to always run the bundled script encourages Claude to use the packaged workflow rather than emit its own ad-hoc git commands — that's how a skill expresses a team's preferred methodology. But this is an instruction the model is strongly inclined to follow, not a hard guarantee: if you need a step to run every time no matter what, enforce it with a hook, not a skill's prose.

Now the crucial distinction the book draws — and the one most people get wrong. Inspect what smart_commit.sh actually produces and you find a minimal, templated commit message: it counts the modified files and drops that number into a fixed string. It is not AI-generated — there's no call to Claude inside the script. The lesson:

A skill is a packaging mechanism, not a guarantee of intelligence. A skill can contain deterministic scripts, AI calls, or both. Wrapping a workflow in a skill does not make it "AI-driven" — the intelligence of the workflow is whatever its scripts and instructions actually do. A skill that shells out to a dumb template produces dumb output, reliably.

That's liberating once you see it: skills let you put deterministic, auditable code (a shell script, a Python validator) on rails inside an agentic workflow. When you want exactness — a precise file transform, a lint, a build step — you write a script and the skill runs it the same way every time. The agent's judgment decides when to run the workflow; the script decides what the workflow does.

Analogy — the appliance button with a program behind it A skill that bundles a script is the "Sourdough" button on a bread machine. The button is a clean, repeatable interface — press it for the same routine every time. But the button isn't the intelligence; the program wired behind it is. Wire it to a rigid timer and you get the same loaf no matter the weather (a deterministic script). Wire it to a smart humidity sensor and it adapts (an AI call — next section). The skill is the labeled button; the script is the program. Pressing a button doesn't make the machine clever — it makes it consistent.

4. Deterministic + AI + graceful fallback

If a script can be deterministic, it can also be smart — because a skill's script can itself call Claude. The book upgrades smart_commit.sh from a static template to an AI-written message by asking Claude to edit the script so it shells out to the CLI:

# inside smart_commit.sh — instead of a static template:
COMMIT_MSG="$(claude -p "Write a one-line conventional-commit message for this diff:
$(git diff --staged)")"
git commit -m "$COMMIT_MSG"

claude -p runs Claude in prompt mode — it takes the prompt, prints the generated message to stdout, and exits — and the script captures that output into the commit. The result is a layered system worth tracing because it's the chapter's most elegant idea:

1. The main agent recognizes your intent and selects the git-pushing skill.
2. The skill runs smart_commit.sh (deterministic orchestration).
3. The script invokes claude -p (an AI call).
4. The CLI generates the commit message.
5. The script consumes that output and completes the commit and push.

As the book puts it: "The skill orchestrates deterministic execution. The script orchestrates an AI call. The AI call generates structured output. The script consumes that output." You've composed a reliable outer shell (the script always runs the same steps) with a flexible inner core (the message is written fresh each time). The book's demo proves the AI is really in the loop by having it write the message in pirate dialect — unmistakably generated, not templated.

Recovery is possible — because a skill injects instructions, not rigid bindings. This is the property that can make skills robust. The book deliberately breaks the skill: it moves smart_commit.sh out of scripts/ and deletes the folder, so the path in SKILL.md is now wrong. In the book's demo, the skill still completes the task. Why? Because a skill doesn't hard-bind to an exact path — it injects instructions ("run smart_commit.sh") into an agent that can still reason. So Claude can read the instruction, look around the repo, find the script in its new location, and run it. And when a script genuinely fails (a git error), Claude can fall back to its own approach — inspect the repo, run git add -A, write a commit itself, and push. The important framing:

Skills provide structured instructions, not deterministic enforcement, and they don't remove the agent's general reasoning. Because Claude remains an agent, it can often reason around a misplaced script or recover from a failed one — but that recovery is a capability, not a guarantee, and what it does in a given run can vary. In the book's demo the boundary was intuitive: a misplaced file could be relocated, a deleted one could not. If you need a step to run reliably every time, don't rely on a skill's prose — put it in a hook or a script that runs outside the prompt-instruction layer.

Two control knobs the book introduces here. A skill's frontmatter can change where and whether it runs:

• context: fork (with agent:) runs the skill in an isolated subagent context instead of the main thread: the skill content becomes the prompt that drives a subagent, the subagent's intermediate reasoning and tool calls stay out of your main window (it doesn't even see your conversation history), and only a summary returns to the main conversation — exactly Chapter 7's isolation. The agent field picks the subagent type (e.g. Explore, Plan). This is the bridge between skills and subagents: a skill can behave like a subagent when you want isolation.
• disable-model-invocation: true stops Claude from auto-selecting the skill — it then fires only when you invoke it explicitly with /skill-name. Use it for skills that should never run unasked.

(One operational note from the book's demo: when you let a skill run without re-confirming each time, Claude records that in settings.local.json. Two distinct permissions are in play — permission to activate the skill, and permission to execute its scripts — and approving "don't ask again" is a settings change, not a change to the skill itself. This is the allowed-tools-style grant from Chapter 3, applied to a skill's script execution.)

Analogy — the assistant with a playbook who isn't a robot You hand a capable assistant a laminated playbook: "to close out, run the closing script." Most days they follow it. One day the script's binder has been reshelved — a good assistant will usually hunt it down and carry on rather than freeze; another day the script jams and they finish the close by hand from experience. None of that is guaranteed — it's the judgment of a professional, not a mechanism — which is why, when a step truly must happen every single time, you bolt it to the door as a rule (a hook), not a line in the playbook. And when you need them out of your hair, you send them to a back room to do the messy parts and bring back just the result (context: fork). The playbook makes them consistent; their judgment makes them adaptable. A skill is the playbook; the agent is still the professional holding it.

5. Skills among the primitives — when to reach for which

You now hold four ways to extend an agent. They overlap enough to confuse, so the chapter closes by separating them. The two comparisons that matter most:

Skills vs MCP. A skill is a procedural-knowledge container — instructions (and scripts) loaded into the agent's own context by progressive disclosure, so the agent reads and follows them. An MCP server is an integration — it connects the agent to an external system and exposes tools the agent calls. The boundary is instruction vs. integration: reach for a skill when you keep re-typing the same procedure; reach for MCP when you keep copying data in from another system. Both are chosen by the agent's judgment against a description, so they feel similar to invoke — but a skill executes in your main agent thread, while an MCP tool executes inside the MCP server (local or remote). (One book-era caveat to correct: the chapter says MCP loads all its tool definitions upfront, making it far less context-efficient than skills. That was true, but current Claude Code defers MCP tool definitions by default — "tool search" — so the context gap is much narrower than the book's table implies. The deeper point still stands: skills carry instructions, MCP carries tools.)

Skills vs subagents. Both let you package dedicated instructions for a task. The difference is context and control. A subagent runs in its own isolated context window with its own system prompt, and returns only a summary — maximum isolation and flexibility, at the cost of more setup. A skill runs inline in the main agent's context, under the main agent's (vendor-managed) system prompt — less flexible, but lighter and shareable. The book's rule of thumb:

- If the task is heavy and would bloat the main context window (lots of files, logs, exploration), use a subagent — isolate it. - If the goal is to give the agent automatic expertise or encode a specific methodology for a recurring task, use a skill — package it. (For a step that must run deterministically every time, reach past a skill to a hook.)

And remember they're not fully separate: a skill with context: fork runs in a lightweight isolated context like a subagent (with fewer controls) — so the line between them is a dial, not a wall.

Slash commands. The book's comparison treats /-commands as a fourth primitive, but here's the current reality (from Chapter 3): custom slash commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave identically. So in the comparison, "slash commands" really names the user-invoked surface — and custom ones are skills. Built-in commands (/clear, /config) remain their own thing.

Here is the comparison, consolidated and corrected against current docs:

The unifying insight: all of these stay affordable through progressive/lazy loading — skills defer their bodies, MCP defers its tool definitions, subagents keep their work in a separate window. The art is matching the shape of the work to the primitive: instructions you want followed consistently → skill; external systems → MCP; heavy isolated work → subagent.

Analogy — four tools on one workbench Picture the bench. A skill is a laminated procedure card in the drawer — you read it into your hands when the job calls for it, and it keeps the team consistent. MCP is the phone line bolted to the wall — it doesn't do the job, it connects you to an outside service that does. A subagent is a colleague you send to the back room with a brief; they work out of sight and hand you a one-page result. And the slash command is the row of quick-dial buttons on the phone — which, you realize, just speed-dial the cards in the drawer. You don't argue about which tool is "best"; you pick by where the work should happen and what it needs.

The whole chapter in one image — the well-run workshop

Analogy — pedagogical summary, drawing on all five sections

Run your agent like a well-run workshop, not a desk piled with every manual open at once.

You don't bury the bench. Pasting every guideline into CLAUDE.md is leaving every manual open on the workbench — you can't find anything, and the clutter slows every job (context bloat). Instead you keep a drawer of labeled procedure cards — skills — each pulled out only when its job comes up (progressive disclosure). A hundred cards cost you a hundred glances at their labels; the detail stays in the drawer until you reach for it.

Some cards drive machines. A card can say "press the jig and run it" — bundling a script that does the exact, repeatable work. The card doesn't make the machine clever; the program behind the button does. Wire it to a fixed timer for determinism, or to a sensor — a claude -p call — when you want it to adapt. Deterministic, AI, or both: the card is just packaging.

Good workers don't freeze. If the jig's been moved, your machinist finds it; if it jams, they finish by hand. A skill injects instructions into an agent that can still reason, so a misplaced or broken script degrades into recovery, not failure — and you can send the messy parts to a back room (context: fork) to keep the main bench clear.

Right tool, right job. The card in the drawer (skill), the phone line to a supplier (MCP), the colleague in the back room (subagent), the quick-dial buttons (slash commands — really just the cards). Match the shape of the work to the tool and the whole shop stays fast and uncluttered. That's the chapter: a skill is the cheapest, most reusable way to make your agent reliably good at one recurring thing — packaging, not magic.

Activity — Decide skill, subagent, MCP, or neither

Ten minutes, individual, no setup required. You'll practice the §5 judgment on tasks from your own work — the discriminating skill this chapter builds.

1. List four recurring tasks you hand an AI agent (e.g., "write our conventional commit message," "look up a ticket's details," "audit a big diff for security issues," "format a response as our house JSON," "explain a module to a new hire").
2. Classify each as best served by a skill, a subagent, MCP, or plain prompting, using the §5 rule of thumb: recurring methodology/expertise loaded into the main context → skill; heavy work that would bloat the main context → subagent; reaching into an external system/data source → MCP; a genuine one-off → just prompt it.
3. For your strongest skill candidate, draft the description. Write the one or two sentences Claude would match against — including the trigger phrases a teammate might actually say. Remember §2: this line, not the body, decides when the skill fires.
4. Name one place a script belongs. For that same candidate, identify a step that should be deterministic (a script), and a step that benefits from AI judgment. Could the script call claude -p for the judgment part?
5. Spot the trap. Which of your four did you want to make a skill but really shouldn't (it's external data → MCP, or a true one-off → just prompt)? Write one sentence on why.

Keep the result — step 3 is the seed of the skill you'll build next.

Practical exercise — Build a skill that bundles a script, then make it think

~35–45 minutes. Hands-on. No web framework, no npm, no accounts — just Claude Code, git, a shell, and a throwaway sandbox. You'll build a real project-level skill with a bundled script, prove progressive disclosure with your own eyes, then upgrade the script from deterministic to AI-assisted and watch it fall back gracefully when you break it.

Everything happens in a throwaway sandbox — nothing here touches the training repo.

Setup (3 min). Create a sandbox with a few files worth summarizing:

mkdir -p ~/cct-ch9-lab && cd ~/cct-ch9-lab
git init -q
printf 'def add(a,b):\n    return a+b\n' > calc.py
printf '# Lab\nA tiny sandbox.\n' > README.md
git add . && git commit -q -m "init skills sandbox"

Part 1 — create a project-level skill (8 min). Build a repo-brief skill that summarizes the repo. Create the folder and file by hand:

mkdir -p .claude/skills/repo-brief/scripts
cat > .claude/skills/repo-brief/SKILL.md <<'MD'
---
name: repo-brief
description: >
  Produce a short brief of this repository's current state. Use when the
  user asks for a repo summary, project status, "what's in here", a
  standup update, or "brief me on this repo".
---
# Repo Brief
When asked for a repo brief:

## Workflow
ALWAYS run the bundled script first, then summarize its output for the user:

bash ${CLAUDE_SKILL_DIR}/scripts/stats.sh

(${CLAUDE_SKILL_DIR} resolves to this skill's own directory wherever it's installed — the portable way to reference a bundled script.) Now the deterministic script itself:

cat > .claude/skills/repo-brief/scripts/stats.sh <<'SH'
#!/usr/bin/env bash
echo "files: $(git ls-files | wc -l | tr -d ' ')"
echo "last commit: $(git log -1 --pretty=%s 2>/dev/null || echo none)"
echo "tracked types: $(git ls-files | sed 's/.*\.//' | sort -u | tr '\n' ' ')"
SH
chmod +x .claude/skills/repo-brief/scripts/stats.sh

Start claude in the sandbox and run /skills — repo-brief should appear. Then ask, in natural language: brief me on this repo.

Expected outcome: Claude recognizes the skill applies (its description matched), asks to use it, runs stats.sh, and summarizes the deterministic output. You never typed /repo-brief — the description routed it. (.claude/skills/ is live-watched, so the skill is picked up without a restart — unless the directory didn't exist when the session started, in which case restart once.)

Part 2 — prove selection follows the listing, not the deep body (8 min). Add a trigger phrase to the body (below the ---), not the description — append a ## When to Use line mentioning "sitrep". Save, /clear, and ask: give me a sitrep. Then instead move that phrase into the description (or add a when_to_use: field), /clear, and ask again.

Expected outcome: editing the deep body doesn't reliably make "sitrep" trigger the skill (the body isn't read until after selection); putting it in the description (or when_to_use) does. That gap is progressive disclosure — Claude routes on the skill listing, primarily the description. (You may find a close phrase still triggers via semantic match to the existing description; the point is that the deep-*body* edit had no effect on selection.)

Part 3 — deterministic vs. AI (12 min). Note that the brief is currently static — stats.sh only echoes counts. Now make it think: ask Claude to edit the script so a one-line, human-friendly summary is generated by the CLI, with a fallback:

# add to stats.sh — AI summary with a graceful fallback:
SUMMARY="$(claude -p "In one friendly sentence, summarize this repo for a standup: $(git ls-files | tr '\n' ' ')" 2>/dev/null || echo 'summary unavailable')"
echo "summary: $SUMMARY"

Re-run brief me on this repo.

Expected outcome: the brief now includes an AI-written sentence — a claude -p call inside a script inside a skill (the layered system from §4). If claude isn't on PATH in the script's environment, the || echo fallback keeps the workflow alive — proving a skill's script can mix deterministic and AI logic and degrade gracefully.

Part 4 — break it and watch it recover (8 min). Move the script and delete the folder the skill names:

mv .claude/skills/repo-brief/scripts/stats.sh .claude/skills/repo-brief/stats.sh
rmdir .claude/skills/repo-brief/scripts

/clear, then ask brief me on this repo again.

Expected outcome: the path in SKILL.md is now wrong, yet in most runs the skill still completes — because a skill injects the instruction "run stats.sh" into an agent that can reason, Claude looks around, finds the file in its new spot, and runs it. This is recovery as a capability, not a guarantee — exactly what to expect (and not over-rely on). Delete stats.sh entirely and it can't recover: the boundary is recover-from-*misplaced*, fail-on-*gone*. (Takeaway: if a step must run every time, enforce it with a hook, not a skill's prose.)

Success checklist

• [ ] You created .claude/skills/repo-brief/SKILL.md and it appeared in /skills; a natural-language request invoked it (no /repo-brief needed).
• [ ] The skill ran its bundled stats.sh rather than improvising — a packaged workflow Claude was guided to follow.
• [ ] You demonstrated that selection follows the skill listing (the description), not the deep body text below the frontmatter.
• [ ] You upgraded the script to call claude -p, composing deterministic execution with an AI call — with a working fallback.
• [ ] After moving the script and breaking the declared path, the skill still completed in your run because Claude reasoned around the moved file — recovery is a capability, not a guarantee (instructions, not rigid bindings).

Common pitfalls - Putting trigger phrases deep in the body and wondering why the skill won't fire. Selection reads the skill listing — primarily the description (with when_to_use appended; the first body paragraph only if description is omitted). Fix the description. - Assuming "wrapped in a skill" means "AI-powered." A skill is packaging. A skill that runs a dumb template produces dumb output. Put the intelligence in the script (or a claude -p call), or in the instructions. - Reaching for MCP when you need a skill (or vice versa). Instructions you want followed consistently → skill. An external system/live data → MCP. Don't stand up a server for what a text file does. - Using a skill for heavy, context-bloating work. That's a subagent's job (isolated context). Consider context: fork if you want a skill to run isolated. - Forgetting the two permissions. Activating a skill and executing its scripts are separate grants; "don't ask again" writes to settings.local.json — review it like any permission change (Chapter 3). - Bloating SKILL.md. Keep it lean (the docs suggest well under ~500 lines) and push detail into bundled files that load on demand — that's the whole point of progressive disclosure.

Knowledge check — try the quiz

Once you've read the lesson and worked the lab, take the chapter quiz from the navigation bar. Six questions: five grounded in the book chapter, one synthesis question that places skills among the other primitives (MCP, subagents, slash commands) and tests the "instruction vs. integration vs. isolation" judgment. Passing score is 5/6 — retake it until you're confident.

Further reading & enrichment sources

• Anthropic docs — "Skills" (https://code.claude.com/docs/en/skills). The canonical reference: the SKILL.md directory format and frontmatter, progressive disclosure (metadata → body → bundled files), how skills are discovered and invoked, allowed-tools as a grant (not a restriction), disallowed-tools / disable-model-invocation / context: fork / agent, the four scopes (personal ~/.claude/skills/, project .claude/skills/, plugin, enterprise), live-change detection, and the note that custom commands have been merged into skills.
• Anthropic docs — "MCP" (https://code.claude.com/docs/en/mcp) and "Subagents" (https://code.claude.com/docs/en/sub-agents). The two primitives skills are compared against — and the current behavior that corrects the book's table (MCP defers tool definitions by default; subagents run in an isolated context and return a summary).
• Anthropic Agent SDK — "Agent Skills" (https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart) and the Agent Skills open standard (https://agentskills.io). Where skills live beyond Claude Code — the API/SDK (container.skills, the pptx/xlsx/docx/pdf document skills) and the cross-product open standard. Treat the ecosystem/standard framing as background, not as Claude Code behavior.
• Anthropic engineering — "Equipping agents for the real world with Agent Skills" (https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills). The post that introduced skills and the progressive-disclosure model (the "well-organized manual that starts with a table of contents" metaphor).
• Anthropic engineering — "Code execution with MCP" (https://www.anthropic.com/engineering/code-execution-with-mcp) and "Effective context engineering for AI agents" (https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents). The broader context-economy argument behind progressive/lazy loading — why deferring detail keeps the working window sharp.
• Community — LangChain DeepAgents (https://docs.langchain.com/labs/deep-agents/overview). The book's non-Anthropic reference point: a LangGraph harness for long-running agents built on the same pillars (detailed system prompts, planning, sub-agents, a file system) — independent convergence on the skills/subagents idea, not a rival.
• Community — claude-skills-marketplace (https://github.com/mhattingpete/claude-skills-marketplace, Apache-2.0). The source of the chapter's git-pushing skill and smart_commit.sh. Read it as a pattern; verify any command syntax against the current docs before relying on it.