Skills

Lesson 3 covered CLAUDE.md, the file Claude reads at the start of every session. That file is the right place for facts: what the project is, which package manager to use, what never to touch. It is the wrong place for procedures. A twelve-step release checklist in CLAUDE.md costs you tokens on every single prompt, including the ones where you only asked Claude to rename a variable. Skills fix that. A skill is a procedure that stays on the shelf until someone reaches for it.

What a skill is and when it loads

A skill is a directory containing a file named SKILL.md. The file has two parts. The top is YAML frontmatter, a short block between two --- lines that tells Claude Code what the skill does and how it may be used. The rest is plain Markdown: the instructions Claude follows when the skill runs. That is the whole format. There is no registration step and no config file listing your skills. Claude Code scans the skill folders and picks up what it finds.

The important idea is what loads when. At session start, Claude Code puts only the skill's name and description into context, one line per skill. The body stays on disk. The body loads in two situations: you type the skill's command, such as /summarize-changes, or Claude reads your request, decides it matches a skill's description, and loads it on its own. The docs call the second path model invocation. A long reference skill therefore costs almost nothing until it is used, which is exactly the opposite of CLAUDE.md.

Once a skill loads, its rendered text enters the conversation as a single message and stays there for later turns. Claude Code does not re-read the file on the next prompt. Write the body as standing instructions, not one-time steps, and keep it short. Every line is a recurring token cost after the first load.

---
description: Draft a window tint quote from a vehicle and film choice. Use when the user asks for a quote, an estimate, or a price for tint.
disable-model-invocation: true
allowed-tools: Read
---

Your instructions go here. Use $ARGUMENTS for whatever follows the command.

Where skills live

Where you save the folder decides which sessions see it. As of September 2026 the Claude Code docs list these locations:

• Personal: ~/.claude/skills/<name>/SKILL.md. Loads in every project on this machine. Cowork and cloud sessions do not read it.
• Project: .claude/skills/<name>/SKILL.md at the repo root. Commit it and everyone who clones the repo gets the skill.
• Nested: <subdir>/.claude/skills/<name>/SKILL.md. A session started in or below that folder loads it at startup. A session started above it loads the skill the first time Claude touches a file in there. If a nested skill shares a name with a root one, both stay available and the nested one is addressed by its path, like /apps/web:deploy.
• Plugin: <plugin>/skills/<name>/SKILL.md, invoked as /plugin-name:skill-name. Lesson 6 covers plugins.
• Enterprise: the same .claude/skills layout inside the managed settings directory, pushed to every machine an organization controls.

One rule ties all of these together: the directory name is the command. A folder called deploy-staging creates /deploy-staging. The frontmatter has a name field, but in a personal or project skill it only changes the display label in listings. The command still comes from the folder. Only plugin skills use name for the command itself. Two small gotchas: do not name a folder synced, because Claude Code reserves that name for skills downloaded from your claude.ai account, and a skill entry can be a symlink to a directory somewhere else on disk. Claude Code follows the link and loads the skill once even if several locations point at the same target. That symlink rule is what makes a shared skills repo practical, which lesson 4 comes back to below.

The frontmatter that matters

The docs list about twenty frontmatter fields. All of them are optional. You will use six of them in the first month:

• description: what the skill does and when to use it. This is the only text Claude has when deciding whether to load the skill, so put the trigger phrases in it. If you omit it, Claude Code uses the first non-empty line of the body. The description plus an optional when_to_use field is capped at 1,536 characters in the listing.
• disable-model-invocation: true: only you can run it. Claude never loads it on its own, and the description is not even placed in context. Use it for anything with side effects, like a deploy or a commit.
• user-invocable: false: only Claude can run it. The skill is hidden from the / menu and typing its name does nothing. Use it for background knowledge that is not an action, like how a legacy billing export works.
• allowed-tools: tools Claude may use without a permission prompt during the turn that invoked the skill. Accepts a space or comma separated string or a YAML list, and permission patterns like Bash(git add *) work here. The grant clears when you send your next message.
• context: fork: run the skill in a separate subagent with its own context instead of your main conversation. Pair it with agent to pick which subagent type, for example the built-in Explore agent for read-only research. Lesson 8 covers subagents.
• paths: glob patterns that limit automatic loading to sessions where Claude is working with matching files, such as src/api/**. The format matches the path-specific rules from lesson 3.

Two habits from the docs are worth adopting on day one. The frontmatter is only read when the opening --- is the very first line of the file, so no blank line above it. And if the YAML is malformed, Claude Code still loads the body with empty metadata. The command keeps working but the description is gone, so Claude stops matching it. Run claude --debug if a skill suddenly stops triggering.

Arguments and live context

A command is more useful when it takes input. Whatever you type after the skill name is available inside the body as $ARGUMENTS. Type /fix-issue 42 and a body line reading "Fix GitHub issue $ARGUMENTS following our coding standards" arrives with the number filled in. You can also pick out individual words: $0 is the first argument, $1 the second, and quoting keeps a multi-word value together. If nothing in the body consumes the arguments, Claude Code appends them at the end as ARGUMENTS: value, so they are never silently dropped. An argument-hint field in the frontmatter shows the expected shape in autocomplete, such as [issue-number].

The second trick is dynamic context injection. A line that starts with an exclamation mark followed by a command in backticks, written as !`git diff HEAD`, is executed before the skill text is sent to Claude. The output replaces the line. Claude never sees the command, only the result, so the instructions arrive with the real diff, the real branch name, or the real test output already inlined. Three details matter. The exclamation mark must be at the start of a line or right after whitespace, so KEY=!`cmd` is left as literal text. For a multi-line command, open a fenced code block with ```! instead of the inline form. And these commands do not run when the skill was synced from a claude.ai account, only from skills on disk.

There are a handful of other substitutions. The docs list ${CLAUDE_SESSION_ID} for the current session, ${CLAUDE_SKILL_DIR} for the folder holding the SKILL.md, and ${CLAUDE_PROJECT_DIR} for the repo root. The skill-dir one is the useful pair with allowed-tools: reference a bundled script by that variable in both the body and the allow rule, and the script runs without a prompt no matter where the skill is installed.

Supporting files, the older commands folder, and the CLAUDE.md rule

Because a skill is a directory, it can carry more than one file. The docs show a layout with SKILL.md as the short overview, a reference.md and examples.md beside it, and a scripts/ folder for helpers. The extra Markdown files load only when Claude decides it needs them, so write a line in the body like "for complete API details, see reference.md." Scripts are executed, not read into context. That split keeps the always-loaded part tiny and the deep material one hop away.

If you have been using Claude Code for a while you may have a .claude/commands/ folder with Markdown files in it. As of September 2026 the docs say custom 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 the same way. The old files keep working and support the same frontmatter, except name and paths. What they lack is a directory, so no supporting files, and there is no reason to start a new one that way. Move a command to a skill by making a folder with the same name and renaming the file to SKILL.md.

That leaves the question every reader of lesson 3 asks: when does something belong in CLAUDE.md and when does it belong in a skill? The docs give a clean test. Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact. CLAUDE.md is for what must be true in every session. A skill is for what should happen on demand. If a rule matters every time Claude edits a file in the repo, it is a fact and belongs in CLAUDE.md. If it is a sequence you run once a week, it is a skill. When in doubt, notice whether you would want Claude reading it while it fixes a typo. If not, it is a skill.

One more practical note. Skills are plain files, so a skills folder can be its own git repository. Lesson 4 shows the setup this site's author uses: the canonical skills live in a versioned repo and are linked into ~/.claude/skills. The docs confirm a skill entry may be a symlink, and lesson 4 shows the exact layout. The same repo is linked into Codex's skills location so both tools read one set of procedures. That is the multi-tool idea from lesson 4 applied to skills instead of rules files.

Try this yourself

This is the first skill the Claude Code docs walk you through, and it is the one to build today because it uses live context. Open a terminal and create the folder:

mkdir -p ~/.claude/skills/summarize-changes

Save this as ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

Now open any git project, make a small edit to one file, and start claude. Test both doors. Ask "What did I change?" and watch Claude load the skill because the request matches the description. Then type /summarize-changes to invoke it directly. Either way you get a short summary of your edit and a list of risks, grounded in the actual diff rather than whatever files happen to be open.

If you created the folder while a session was already running, the skill appears without a restart. Claude Code watches the personal and project skill folders and picks up new or edited SKILL.md files mid-session. The one exception: if the top-level ~/.claude/skills directory did not exist when the session started, restart once so Claude Code can begin watching it. Once this works, go back to the builder above and sketch the first procedure you are tired of pasting.