Lesson 3.318 min · 5 cards · 8 exercises · 1 mission

Agent Skills

Skills Claude knows when to use: the description, reference files, bundled scripts, who may invoke them, and running in a subagent.

In lesson 3.2, /add-endpoint was a command: you type it, Claude does the work. But plenty of team habits shouldn't depend on someone remembering a command. Take the review checklist every change must pass before a pull request. If Claude notices when you say "I'm about to open a PR", reads the checklist and runs the check script on its own, the checklist gets used every time, not only when someone remembers it. This lesson writes that skill for todo-api.

What makes it a skill, not a command

On disk nothing changes: it is still a .claude/skills/<name>/ folder with a SKILL.md. The difference is how it gets used. The command from lesson 3.2 is a prompt you run by hand. An Agent Skill is a package of know-how: instructions, reference material and scripts in one folder, and Claude decides on its own when to use it based on its description.

Claude Code skills follow the Agent Skills open standard (agentskills.io), so a well-written skill can be reused by other AI tools that follow the same standard. Claude Code adds fields of its own, such as disable-model-invocation, context and argument-hint.

The description decides when Claude reaches for it

When a session starts, Claude does not read every SKILL.md. Claude Code loads a listing with each skill's name and description. The full content only loads when the skill is invoked. So the description is all Claude has to go on when deciding whether your skill fits the moment.

A good description answers two questions: what the skill does, and when to use it, in the words people actually say.

YAML
# Too vague: Claude can't tell when it's needed
description: Review helper

# Good: says the job, says the moment, uses the words people type
description: Review the current branch against the todo-api team checklist. Use when the user asks to review their changes, check a branch, or get ready to open a pull request.

A few limits worth knowing:

  • The description plus the optional when_to_use field is cut at 1,536 characters in the listing. Put the main use case first.
  • The whole listing has a budget of about 1% of the context window. With too many skills, Claude Code drops the descriptions of the ones you use least, and those become hard for Claude to pick at the right moment. Run /skill-doctor to see which skills cost space and never get used.

When a skill misbehaves:

  • It never triggers: add the words people would naturally say, and ask "What skills are available?" to check it is listed.
  • It triggers too often: make the description more specific, or add disable-model-invocation: true.

Supporting files and scripts

A skill is a folder, so it can hold more than one file:

.claude/skills/pr-review/
├── SKILL.md            (required: overview and steps)
├── checklist.md        (read by Claude when needed)
└── scripts/
    └── red-flags.sh    (run by Claude, never loaded into context)

The three kinds of file are used in three ways:

  • SKILL.md loads when the skill is invoked. The docs advise keeping it under 500 lines.
  • Reference files such as checklist.md are read only when Claude needs them. Point to each one from SKILL.md and say what is in it and when to read it, for example "check each item in [checklist.md](checklist.md)". Long material costs nothing here until it is used.
  • Scripts are run, and only their output enters the context. Anything that needs an exact answer, such as finding banned lines, counting or checking a format, belongs in a script rather than in Claude's judgement.

To run a script, use ${CLAUDE_SKILL_DIR}, the folder that holds SKILL.md. The path then resolves correctly whether the skill lives in the project, in ~/.claude/skills/ or in a plugin. The variable is replaced in two places: the skill's content and the Bash(...) rules in allowed-tools. Use it in both and the script runs without a permission prompt:

YAML
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/red-flags.sh *)

When we tried this for real, we hit one snag. Claude sometimes shortened the path to .claude/skills/..., or chained the script with another command. The command then no longer matched the rule, so Claude Code asked for permission anyway. Spell it out in the step: "run exactly this command, on its own, with the full path as written".

Compare this with !`command` from lesson 3.2. An injected command runs before Claude reads the skill. A bundled script is run by Claude when it reaches that step, and Claude can read the output and decide what to do next.

Who invokes it, and where it applies

Lesson 3.2 used disable-model-invocation: true to make a skill yours only. The opposite is user-invocable: false: only Claude invokes it, and it is hidden from the / menu. Use it for background knowledge that isn't an action, such as a legacy-billing skill explaining the old billing system. Claude should know it when touching that code, but typing /legacy-billing would do nothing useful.

Frontmatter You can invoke Claude can invoke Description in context
(default) Yes Yes Yes
disable-model-invocation: true Yes Not on its own No
user-invocable: false No Yes Yes

user-invocable: false only hides the skill from the menu. It doesn't stop Claude from invoking it. To stop Claude, use disable-model-invocation: true.

Depending on your permission mode, Claude Code may ask you before Claude invokes a skill on its own. In our test in the default mode, the first call to pr-review needed approval. A Skill(pr-review) allow rule in your settings skips that question; Skill(deploy *) as a deny rule blocks the deploy skill outright.

The paths field takes glob patterns, with the same syntax as the path-scoped rules from lesson 2.3. The skill only activates when Claude works with matching files, for example a route-conventions skill that only matters under src/routes/**. Patterns are relative to the working directory, so they don't apply to files outside it, not even a sibling git worktree.

Run it on its own: context: fork

Add context: fork and the skill runs in a new subagent (a helper agent with its own context, the topic of level 4). The agent field picks its type: Explore, Plan, general-purpose (the default) or an agent you defined yourself.

YAML
---
name: deep-research
description: Research a topic in this codebase thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS: find the relevant files, read them,
and summarise with file references.

Three things to remember:

  • The subagent doesn't see your conversation history. The skill content is its whole task, so it must make sense on its own.
  • It only suits skills with a concrete task. A skill that just says "follow these API conventions" gives the subagent guidelines with nothing to do, and it returns without meaningful output.
  • By default the subagent runs in the background: you keep working and the result arrives when it finishes. Set background: false to wait for it in the same turn.

Our pr-review skill needs to see what you are working on, so it stays in the main conversation.

A PR review skill for todo-api

Putting it together, here is SKILL.md:

Markdown
---
name: pr-review
description: Review the current branch against the todo-api team checklist. Use when the user asks to review their changes, check a branch, or get ready to open a pull request.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/red-flags.sh *)
---
Review this branch against main before a pull request.

1. Run exactly `${CLAUDE_SKILL_DIR}/scripts/red-flags.sh main` on its own, full path as written, and list every line it prints
2. Read the diff with `git diff main...HEAD`
3. Check each item in [checklist.md](checklist.md): pass, fail or n/a, with file:line for each fail
4. End with one verdict: ready, ready after fixes, or not ready

checklist.md holds the team's checklist. Every new route has a test. Errors come back as { error: "..." }. A missing or deleted todo returns 404, never 500. No console.log is left behind, and npm test passes.

scripts/red-flags.sh finds newly added lines the team never merges:

Terminal
#!/usr/bin/env bash
# Print added lines the team never merges: console.log, debugger, test.only
base="${1:-main}"
git diff "$base"...HEAD -U0 -- src test \
  | grep -E '^\+[^+].*(console\.log|debugger|\.only\()' \
  || echo "No red flags against $base"

Remember to chmod +x the script. The || echo keeps the exit code at 0 even when nothing is found.

Test the skill in a fresh session, because leftover context from writing it hides gaps in the instructions. Say "I'm about to open a PR for this branch, can you look it over?" without typing /pr-review. When we tried it, Claude invoked the skill, ran the script, pointed to both console.log lines with line numbers and concluded "ready after fixes". To find out whether the skill really helps, ask the same question in another fresh session with the skill turned off (/skills, highlight it, Space to switch it off, Esc to save) and compare.

Last, a skill is guidance, not law. When a long session is compacted, Claude Code keeps only the start of each invoked skill, so put what matters most at the top. Anything that must hold every time, such as never writing to .env, belongs in a hook (level 6).

Commit .claude/skills/pr-review/ and the whole team gets a reviewer who knows the checklist. Next level: handing work to specialised agents.

Practice lesson 3.3

5 flashcards, 8 exercises checked right on the page, 1 mission on your machine.

Start practice

Related reference

Type to search the reference, templates and lessons.