A Skill Pack for a Real Project
One skill saves a few minutes. A small, well-chosen set of them gives a project its own vocabulary: "explain this endpoint", "review this diff against our checklist", "draft release notes", "is the build healthy". This chapter designs that pack for the bookshelf project, adds a skill that carries a supporting checklist file, runs it for real, and covers how to test, share and secure a pack.
Choosing What Belongs in a Pack
Turn a repeated request into a skill when you have typed it three times and the good version has a stable shape. Then answer four questions for each one. This is the author's checklist, not an Anthropic rule.
The bookshelf pack, decided that way:
| Skill | Started by | Runs | Tools | Stop rule |
|---|---|---|---|---|
explain-endpoint | You or Claude | Forked, Explore agent | read only | "Read only. Do not edit files" |
verify-build | You or Claude | Inline | Bash(./mvnw *) | "Do not edit any files" |
review-diff | You or Claude | Inline | Bash(git diff *) | "Do not review code that is not in the diff" |
release-notes | You only | Inline | Bash(git log *) | "Needs a human" instead of guessing |
Notice that none of them edits code. The first pack to write is the one that reads, checks and reports; skills that change files deserve the plan-first habits of Chapter 16 and a human reading the diff.
review-diff: a Skill With a Supporting File
A review is only as good as its criteria, and criteria change more often than the procedure. Keep them in a separate file the skill points at. The body stays short, the checklist can be edited without touching the skill, and Claude reads the file only when it reviews (Source 1).
Run on the commit that added title search (/review-diff HEAD~4..HEAD~3), the diff is injected by the ! line, and Claude reads the checklist, then reports against it:
Real sample: what Claude answered (Checked)
Four Skills, One Folder
The fourth skill, verify-build, is shown for completeness. It was not run in this chapter.
Skills stack in a terminal session, so a pre-merge routine is a single line: /verify-build then /review-diff main..HEAD then /release-notes main..HEAD (Source 1). Names are the interface of your project, so choose them like function names: a verb and an object, no abbreviations.
Testing a Skill Like Code
Skills fail in three ways: they do not load, they do not trigger, or they trigger and misbehave. Each has a test.
| Failure | Test | Done in this guide? |
|---|---|---|
| Does not load | Start a one-turn session and check the start-up event lists the name | Yes, Chapter 18 (and the control, release-notes, was listed) |
| Does not trigger | Plain-words prompts that should trigger it; count Skill tool calls | One positive case (Chapter 18). No negative case |
| Misbehaves | Run it on a known input and compare against what you can verify | Yes: line references in the three samples were checked against the code |
A habit worth copying: keep the prompts you used to test each skill next to it (in the examples repository they sit in prompts/samples/ with the answers). When you edit a skill's description, re-run them.
Sharing a Pack, and Trusting One
- Project skills in
.claude/skills/travel with the repository, so teammates get them on clone. - Personal skills in
~/.claude/skills/follow you across projects. - Plugins bundle skills (invoked as
/plugin-name:skill-name) with agents, hooks and MCP servers for wider sharing; Chapter 12 built one, and Chapter 24 will cover distribution.
! lines execute before Claude reads anything, subject to permission rules, and a skill can also register hooks. Read a third-party skill the way you read a script you are about to run. Anthropic documents a setting, disableSkillShellExecution, that replaces injected commands with a policy message; managed environments can use it (Source 1). Also see Chapter 13 on untrusted repositories.Key Takeaways, Exercises and Sources
- Four decisions per skill: who starts it, where it runs, which tools, and what it must not do.
- Start with skills that read and report. Skills that edit need a human reading the diff.
- Keep changing criteria in a supporting file (the review checklist) so the skill stays short.
- Test loading, triggering and behaviour separately, and keep the test prompts.
- Treat a skill like a script: it can run commands and register hooks.
Exercise 1 Beginner
List five requests you typed to Claude this month. For each, answer the four design questions in one line. Which ones are worth a skill?
Learning outcome: choose what to automate.
Exercise 2 Intermediate
Write a review-diff for your own repository with a five-item checklist taken from your real code reviews. Run it on three past commits and compare its findings with what a human reviewer said then.
Learning outcome: encode review criteria and check them against reality.
Exercise 3 Advanced
Build a test script that starts one-turn sessions with stream-json output and asserts that your skills are listed and that three trigger phrases cause a Skill call. Run it in CI after any change under .claude/skills/. Remember that such runs cost money, so cap them with --max-budget-usd.
Learning outcome: regression-test your agent configuration.
- Anthropic, Extend Claude with skills — supporting files, stacking, plugin invocation, injection and its permission rules,
disableSkillShellExecution. The last roughly 19,000 characters of the page were not read.
The review-diff run (SK-03) was executed on 2026-10-31. verify-build was not run here. The design checklist and the table of decisions are the author's own. Skill files are in the examples repository under skills/.