Skills

Take .claude/commands/changed.md from the last module, make a directory called changed, and move the file into it as SKILL.md. You now have a skill. /changed still works, the body is unchanged, and nothing you learned about $0 or ! injection has been invalidated.

Four things arrive with the directory. Supporting files that sit next to SKILL.md and load only when Claude reads them. A scripts/ folder for code that gets executed rather than read into context. The name and paths frontmatter fields, which a command file ignores. And automatic invocation, where Claude decides the skill is relevant and loads it without you typing anything.

The docs recommend skills over command files for exactly the first reason: they support supporting files.

The shape on disk

#!/usr/bin/env bash
set -euo pipefail
path="${1:-.}"
git diff --stat -- "$path" || true
git diff --name-only -- "$path" | head -50

---
description: Summarize uncommitted changes and flag anything risky.
when_to_use: When the user asks what changed, wants a commit
message, or asks you to review their diff.
argument-hint: [path]
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/summarize.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/summarize.sh $0` and read
its output.

Summarize the changes in two or three bullets, then list
anything risky: missing error handling, hardcoded values,
tests that will now fail.

Conventions for this repo are in reference.md next to this
file. Read it when the diff touches the API layer.

# Repo conventions

API handlers return typed errors, never raw strings.
Migrations are forward-only.
Anything under legacy/ is exempt from all of the above.

---
description: Summarize uncommitted changes and flag anything risky
---

(superseded by .claude/skills/changed/)

Where the name comes from

For a personal or project skill, the command name is the directory name. deploy-staging/SKILL.md gives you /deploy-staging. Frontmatter name is a display label in listings and nothing more.

That rule has one exception, and it is the reason people get confused. For a plugin skill, frontmatter name does set the last segment of the command, so name: fancy in a plugin called my-plugin produces /my-plugin:fancy. You will meet that in module 12. Until then, the directory decides.

description and when_to_use

description says what the skill does and when it applies. when_to_use carries the trigger phrases and is appended to the description. They are one budget: the combined text is truncated at 1,536 characters in the listing Claude sees. If you omit description entirely, the first paragraph of the body is used.

Write when_to_use in the vocabulary a user would actually type. “When the user asks what changed, wants a commit message, or asks you to review their diff” earns its place. “For diff-related tasks” does not.

Who can invoke what

Two true-or-false fields produce three useful states.

The docs sort skills by what is in them. Reference content, such as conventions or a style guide, is worth letting Claude reach for on its own. Task content, such as deploy or send-slack-message, should be disable-model-invocation: true. The stated reason is blunt: “You don’t want Claude deciding to deploy because your code looks ready.”

disable-model-invocation: true also blocks preloading into subagents, and blocks scheduled tasks from firing the skill.

Tool grants clear on your next message

allowed-tools pre-approves tools for the invoking turn only. Your next message clears the grant. disallowed-tools behaves the same way in reverse, removing tools from the pool while the skill is active.

Both fields swap ${CLAUDE_SKILL_DIR} and ${CLAUDE_PROJECT_DIR} for the real folder they stand for, and so does the body. That double substitution is the mechanism that makes a bundled script runnable without a prompt:

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

The rule and the call resolve to the same absolute path, so the call matches an allow rule. Write the grant with a relative path and it will not match, and you will get an approval prompt on every run.

The economics of progressive disclosure

The description is always in context, for every skill Claude can see, in every session. It is a fixed tax you pay whether or not the skill is ever used. Listings have their own budget, governed by skillListingBudgetFraction, which defaults to 0.01 of the context window. Go over it and the descriptions of your least-used skills get dropped, which means they stop being matchable.

The body loads when the skill is invoked, and then stays for the whole session. Claude Code does not re-read the file on later turns.

One line always, the rest only on demand: that split is what progressive disclosure names in the heading above. Two consequences follow from it directly.

First, write standing instructions, not one-time steps. A body that reads “now do X, then report back” is wrong, because that text is still sitting in context four turns later saying “now do X”. Write rules that remain true.

Second, every line in the body is a recurring cost for the rest of the session, not a one-time read. A 400-line skill invoked in minute two is still occupying context in minute ninety. The docs cap the guidance at 500 lines, and that is a ceiling rather than a target. Anything that can live in a sibling reference.md and be read on demand should. Anything that can be a script in scripts/ costs nothing at all, because it is executed rather than loaded.

Re-invoking a skill whose rendered content has not changed adds only a short “already loaded” note.

A long session eventually runs out of room, and Claude Code compacts it to make space. Under that auto-compaction, the most recent invocation of each skill is re-attached, keeping the first 5,000 tokens of each within a shared 25,000-token budget, filled newest first. Older skills fall off the end.

Precedence

Module 3 said instruction files have no precedence, no fixed order that picks a winner. Skills do. When the same skill name exists at more than one level, the winner is fixed:

enterprise > personal > project.

Personal beats project. That is the opposite of what most configuration systems do, and the opposite of what you will find in module 8, where subagents resolve managed > project > user. Two surfaces, two orders. Do not generalise from this one.

The rest of the resolution rules, in order: any of the three levels overrides a bundled skill of the same name, but not that bundled skill’s aliases, so a project code-review skill does not capture /review. Plugin skills carry their plugin’s name in front, as plugin-name:skill-name, so two plugins can each ship a deploy and never collide. That prefix is a namespace. A skill beats a same-named .claude/commands/ file. Anything local beats a claude.ai-synced skill.

Project skills load from .claude/skills/ in your working directory and every parent up to the repo root. Skills nested below your working directory load lazily, meaning not until Claude reads or edits a file in that subtree, and on a name clash they take the directory as a prefix, such as /apps/web:deploy.

Check yourself

1. Your skill lives in .claude/skills/ship/ and its frontmatter says name: deploy. What do you type?
2. A personal skill and a project skill are both called changed. Which one runs?
3. You invoke a skill in your second message and keep working for an hour. How many times is SKILL.md read from disk?