Progress will not be saved. This browser is blocking storage (often private browsing). You can still learn, but closing the tab loses your progress.
Practice needs JavaScript. The reading works without it.Back to the reading
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.
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.
# 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
descriptionplus the optionalwhen_to_usefield 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-doctorto 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.
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.mdloads when the skill is invoked. The docs advise keeping it under 500 lines.- Reference files such as
checklist.mdare read only when Claude needs them. Point to each one fromSKILL.mdand 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:
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.
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.
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.
---
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: falseto 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.
Putting it together, here is SKILL.md:
---
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 readychecklist.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:
#!/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.