What you will be able to do
- Write a description that tells Claude both what a skill does and when to use it
- List the frontmatter fields SKILL.md accepts and which of them command files can't use
- State what the documentation says about allowed-tools and the permission flow, and what it doesn't say
- Tell apart what these sources establish about argument-hint and context from what you'll need the full frontmatter reference for
1.The description decides when a skill fires
A SKILL.md opens with a YAML frontmatter block between --- lines, followed by the instructions in Markdown. The field that shapes behaviour most is description. At startup Claude reads each skill's name and description into its system prompt, and it compares your requests against them to decide whether a skill applies. So a description has two jobs: say what the skill does and say when to use it.
---
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.
---The first sentence says what the skill does. The "Use when…" sentence lists the requests that should trigger it: what changed, a commit message, a diff review. That is why the documented test for this skill has two parts. Asking "What did I change?" in plain language should trigger it automatically, and typing /summarize-changes invokes it directly. A description with only the first sentence still documents the skill, but Claude has less to match against.
Sources1
2.The body, and the files beside it
Everything below the frontmatter is the skill's body: the procedure Claude follows once the skill is triggered. At that point Claude reads SKILL.md from the filesystem, and only then does the body enter the context window. The body can also point to other files in the same folder, such as a detailed reference or a helper script. Claude opens those only when the task needs them, and when it runs a script, only the script's output enters context, not its code.
This is the practical reason the documentation prefers a skill folder to a single command file for new work. A long reference can sit in its own file without making the everyday case more expensive, and a deterministic step can be a script rather than instructions Claude has to follow correctly each time.
Nothing. Bundled files cost no tokens until they are accessed, and Claude opens a referenced file only when the task needs it.
Sources1
3.The fields SKILL.md accepts
Back to the release helper: "Release helper." gives Claude nothing about when to use the skill, so a request worded differently has nothing to match. Besides description, SKILL.md frontmatter accepts many fields. The .claude directory reference lists them all, and command files in .claude/commands/ accept all of them except name and paths. Three matter for this objective: allowed-tools, argument-hint and context.
| Field | Accepted in SKILL.md | Accepted in commands/*.md | Behaviour documented in these sources |
|---|---|---|---|
| description | Yes | Yes | What Claude matches your request against to decide whether to trigger the skill |
| allowed-tools | Yes | Yes | A grant that goes through the normal permission flow, honoured in every kind of session |
| disallowed-tools | Yes | Yes | Listed only; no behaviour described |
| argument-hint | Yes | Yes | Listed only; no behaviour described |
| context | Yes | Yes | Listed only; no behaviour described |
| name, paths | Yes | No | The two skill fields command files do not support |
4.allowed-tools and the permission flow
The exam guide describes allowed-tools as a way to restrict a skill's tool access, for example to file-writing operations, so that it can't take destructive actions. The one behavioural statement in these sources is narrower. Claude Code honours skill frontmatter in every kind of session, and an allowed-tools entry is a grant that passes through the normal permission flow. It doesn't sidestep the permission system.
What these sources don't say is whether listing tools in allowed-tools blocks the tools you left out. The same field list includes a separate disallowed-tools field, which suggests blocking is its own setting. These sources don't describe how it behaves, though. Before an exam question depends on whether a skill can still run a shell command, check the skill frontmatter reference in the Claude Code documentation. Don't assume a list of allowed tools is also a list of the only tools.
A developer keeps invoking a skill that walks the entire codebase and prints a long dependency analysis. Even after the skill finishes, this lengthy output keeps consuming space in the main conversation for the rest of the session. What frontmatter change would keep this analysis out of the main conversation's context while still returning a summary?
Correct answer: B — Add `context: fork` to the skill's frontmatter so the analysis runs in an isolated subagent and only a summarized result is returned to the main conversation.
- A. Incorrect. `argument-hint` only shows an autocomplete placeholder; it doesn't change scope of the scan or where the output lands.
- B. Correct. `context: fork` runs the skill in an isolated subagent context; the verbose analysis stays in that forked context and only the returned result surfaces in the main conversation.
- C. Incorrect. Restricting tool access changes which tools can run, not whether the resulting output pollutes the main conversation's context.
- D. Incorrect. Preventing automatic invocation only changes who can trigger the skill; once invoked, the verbose output would still land directly in the main conversation.
These sources don't support that. They say the allowed-tools grant goes through the normal permission flow, so the contractor's session settings still apply.
A team's `explore-alternatives` skill asks Claude to brainstorm several competing architecture approaches before settling on a recommendation. The team wants that exploratory back-and-forth kept separate from the main conversation, with only the final recommendation surfacing back to the user. Which configuration accomplishes this?
Correct answer: A — Set `context: fork` on the skill so the brainstorming happens in a subagent, and only the returned result reaches the main conversation.
- A. Correct. `context: fork` isolates the exploratory reasoning in a subagent context, so the brainstorming itself never enters the main conversation, and only the resulting recommendation is surfaced back.
- B. Incorrect. This only restricts who can trigger the skill; it does nothing to keep the brainstorming content out of the main conversation once invoked.
- C. Incorrect. This only hides the skill from the `/` menu; the skill would still run inline in the main conversation, exposing the full brainstorming.
- D. Incorrect. `paths` only controls when a skill auto-activates based on file patterns; it has no effect on whether the skill's output is isolated from the main conversation.
Sources3
5.argument-hint and context: what these sources cover
The exam guide names two more fields. argument-hint is meant to show developers which parameter to type when they invoke a skill without one. context: fork is meant to run a skill in an isolated sub-agent, so verbose output such as a codebase analysis, or exploratory work such as brainstorming alternatives, stays out of the main conversation. These sources confirm that both argument-hint and context are valid SKILL.md fields, and valid in command files too. They don't document the fork value or what argument-hint displays, so this lesson makes no claims beyond that.
An engineer keeps pasting the same eight-step deployment checklist into chat whenever they ask Claude to help ship a release, and the same steps have started to also live as a growing section in the project's `CLAUDE.md`. They want the procedure available on demand without it consuming context on every single turn of every session. What should they do?
Correct answer: D — Move the checklist into a `deploy-checklist` skill under `.claude/skills/`, since a skill's body only loads into context when it's invoked, unlike `CLAUDE.md` content which loads every session.
- A. Incorrect. Expanding the `CLAUDE.md` section would load the detailed steps into every session, consuming context continuously, which is exactly the recurring cost the engineer wants to avoid. The goal is to have the procedure available on demand without bloating every session's baseline context.
- B. Incorrect. Subagent definitions under `.claude/agents/` describe an agent's own configuration and are not a mechanism for storing procedural checklists that load on demand. They do not conditionally inject content into the main session in the way skills do, and using them for this purpose would not keep the main session focused without overhead.
- C. Incorrect. Hooks in `settings.json` are designed for automated event-triggered scripts, such as running a command before tool use, not for holding a multi-step interactive checklist that Claude follows conversationally. A `PreToolUse` hook would execute rigidly rather than providing the flexible, on-demand guidance the engineer needs.
- D. Correct. A skill's body loads into context only when it is invoked, so moving the checklist into a `deploy-checklist` skill keeps it available on demand without adding to every session's baseline context, unlike `CLAUDE.md` content which loads every session.
Sources2
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Setting allowed-tools in SKILL.md bypasses permission prompts, so a committed skill runs its listed commands without approval on any teammate's machine.Why is that wrong?
The documented behaviour is that an allowed-tools grant goes through the normal permission flow. It doesn't override the permission system in any session.
Covered in allowed-tools and the permission flow
2.A skill's description is only a label for humans, so a short name-like description is enough for Claude to use the skill automatically.Why is that wrong?
Claude matches requests against the description to decide whether to trigger the skill, so it has to say both what the skill does and when to use it.
Covered in The description decides when a skill fires
Practise it for real
Create a personal skill, trigger it both ways, and decide whether it should become a project skill.
1.Run: mkdir -p ~/.claude/skills/summarize-changes
Why: A skill is a named folder. Putting it under ~/.claude/skills/ makes it personal, so it's available in all your projects and your teammates never see it.
You should see: An empty summarize-changes directory in your home skills folder.
2.Create SKILL.md in that folder with the documented frontmatter description, a '## Current changes' section containing !
git diff HEAD, and an '## Instructions' section asking for a two-to-three bullet summary plus risks.Why: The description tells Claude when to use the skill. The body holds the procedure, which is loaded only when the skill runs.
You should see: A SKILL.md whose frontmatter has a description saying both what it does and when to use it.
3.In a repository with uncommitted edits, start Claude Code and ask: What did I change?
Why: This checks automatic invocation: the plain-language request should match the description.
You should see: Claude summarises the diff and lists risks, without you typing the command name.
4.Type /summarize-changes
Why: This checks direct invocation by name.
You should see: The same kind of summary, triggered explicitly.
5.Decide whether the team should have it. If so, move the folder to the repository's .claude/skills/summarize-changes/ and commit it. If you keep a personal version too, give it a different folder name.
Why: The project location is shared through version control. A same-named personal copy would override the team's version in your sessions.
You should see: Teammates get /summarize-changes after pulling, and your personal variant, if you keep one, has its own name.
Stuck? Get a nudge
If the plain-language request doesn't trigger the skill, reread the description. Does it say when to use the skill, or only what it does?
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“The description is what Claude matches your request against when determining whether to trigger the Skill”
↩︎ The description decides when a skill fires“Claude reads SKILL.md from the filesystem using bash. Only then does this content enter the context window.”
↩︎ The body, and the files beside it“Executable scripts (fill_form.py, validate.py) that Claude runs using bash, providing deterministic operations without loading their code into context”
↩︎ The body, and the files beside it“The description is what Claude matches your request against when determining whether to trigger the Skill”
↩︎ Exam trap 2 - 2.https://code.claude.com/docs/en/claude-directoryOfficial docs
“name, description, when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, allowed-tools, disallowed-tools, model, effort, context, agent, background, hooks, paths”
↩︎ The fields SKILL.md accepts“argument-hint, arguments, disable-model-invocation, user-invocable, allowed-tools, disallowed-tools, model, effort, context, agent”
↩︎ argument-hint and context: what these sources cover - 3.https://code.claude.com/docs/en/skillsOfficial docs
“It supports the same frontmatter except name and paths.”
↩︎ The fields SKILL.md accepts“Claude Code honors the frontmatter in every kind of session, so an allowed-tools grant goes through the normal permission flow.”
↩︎ allowed-tools and the permission flow“Claude Code honors the frontmatter in every kind of session, so an allowed-tools grant goes through the normal permission flow.”
↩︎ Exam trap 1