What you will be able to do
- Use argument-hint to show developers what arguments a skill expects, and know how those arguments reach the skill body
- Tell allowed-tools (pre-approves tools) apart from disallowed-tools (removes tools), and pick the right one for a goal
- Use context: fork to run verbose or exploratory skills in an isolated subagent so their output stays out of the main conversation
1.Telling developers what to type: argument-hint
Frontmatter is the YAML block at the top of SKILL.md, and it controls how a skill behaves. Most fields are optional. description is recommended, because Claude uses it to decide when to apply the skill.
Take a skill invoked as /fix-issue 482. The arguments after the name reach the skill body through placeholders. $ARGUMENTS holds all of them, and $0 or $ARGUMENTS[0] holds the first one by 0-based index. With an arguments field such as arguments: [issue, branch], you can write $issue and $branch instead. If the body has no placeholder, Claude Code appends the input as ARGUMENTS: <value>.
Teammates still have to know that the skill expects an issue number. That is the job of argument-hint. Its value appears during autocomplete, so someone typing /fix-issue sees something like [issue-number] and knows what to supply. The docs describe it only as a hint shown in autocomplete. It tells people what to type, and does nothing to check what they actually pass.
| Field or variable | Role |
|---|---|
| argument-hint | Hint shown during autocomplete, e.g. [issue-number] or [filename] [format] |
| arguments | Named positional arguments for $name substitution, mapped to positions in order |
| $ARGUMENTS | All arguments passed when invoking the skill |
| $N / $ARGUMENTS[N] | A specific argument by 0-based index |
Checkpoint 1 of 6· Check yourself
A skill's body uses $0 and $1, and teammates keep invoking it with nothing after the name. Which frontmatter change helps them most?
argument-hint is the field shown during autocomplete. The arguments field only names positions for $name substitution, and user-invocable already defaults to true.
“Hint shown during autocomplete to indicate expected arguments.”Source: code.claude.com
Checkpoint 2 of 6· Exam question
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.
Sources1
2.allowed-tools pre-approves; disallowed-tools restricts
---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---
Your skill instructions here...The name allowed-tools sounds like an allowlist, but it works as a grant. The tools it lists run without a permission prompt during the turn that invokes the skill, and the grant clears when you send your next message. Every other tool is still there and is handled by your normal permission settings. Claude Code honors this frontmatter in every kind of session, and the grant still goes through the normal permission flow.
To actually stop a skill from using certain tools, use disallowed-tools. It removes the listed tools from Claude's pool while the skill is active, and the docs recommend it for autonomous skills that should never call certain tools. For a report generator that should write files but never touch the shell, the restriction comes from disallowed-tools: Bash. You can add allowed-tools: Write Edit on top so file writes don't prompt. If you list only Write and Edit under allowed-tools, you remove the prompts for those two tools and nothing is restricted. Note that the example above, allowed-tools: Read Grep, pre-approves read-only tools. That is a safe use of the grant, because nothing it skips prompting for can change files.
| Field | Effect | Lasts until | Use it to |
|---|---|---|---|
| allowed-tools | Listed tools run without asking permission | You send your next message | Remove approval prompts for tools the skill needs |
| disallowed-tools | Listed tools are removed from Claude's available pool | You send your next message | Guarantee a skill never calls certain tools |
Checkpoint 3 of 6· Fill the gap
Which frontmatter key makes Read and Grep run without a permission prompt when this skill is invoked?
---
name: my-skill
description: What this skill does
disable-model-invocation: true
? : Read Grep
---
Your skill instructions here...allowed-tools pre-approves the listed tools for the invoking turn. disallowed-tools would remove Read and Grep instead, and tools is a subagent field, not a skill field.
Source: code.claude.comCheckpoint 4 of 6· Exam question
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.
Checkpoint 5 of 6· Exam question
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.
Sources1
3.Isolating noisy skills with context: fork
A normal skill runs inside your conversation, so its content and everything it produces go into your main context window. That is fine for a short checklist. It causes problems for a skill that reads dozens of files to analyse a codebase, or one that explores and rejects several alternatives. The features overview puts it this way: when a side task floods your conversation with output you won't reference again, send it through a subagent.
context: fork does this for a skill. It runs the skill in a forked subagent. A new, isolated context is created, the skill's content becomes the subagent's prompt, and only a summary comes back to your conversation.
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file referencesThree related fields only apply when context: fork is set. agent picks the subagent type, and that type determines the execution environment: model, tools and permissions. model, when combined with fork, sets the forked subagent's model rather than overriding the session model. background defaults to true, so the fork runs in the background. Set background: false if the invoking turn should wait for the result. The docs' deploy example pairs context: fork with disable-model-invocation: true, so a multi-step deployment only runs when someone types /deploy and its output stays out of the main session.
Checkpoint 6 of 6· Put it in order
Put the stages of a context: fork skill run in order
- 1.The subagent receives the skill content as its prompt
- 2.The subagent works in the environment set by the agent field
- 3.The subagent summarizes its results and returns them to your main conversation
- 4.A new isolated context is created
The fork creates a fresh context, gives it the skill body as its prompt, runs it with the agent type's model, tools and permissions, and returns only a summary.
“The subagent summarizes its results and returns them to your main conversation when it finishes”Source: code.claude.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Setting allowed-tools: Write Edit limits a skill to file writes and stops it from running shell commands.Why is that wrong?
allowed-tools only pre-approves the listed tools for the invoking turn. Removing tools is the job of disallowed-tools.
Covered in allowed-tools pre-approves; disallowed-tools restricts
2.A context: fork skill always blocks the current turn until the subagent finishes.Why is that wrong?
background defaults to true for forked skills. You must set background: false to make the invoking turn wait for the result.
Covered in Isolating noisy skills with context: fork
Practise it for real
Create a personal skill, invoke it, then add context: fork to it
1.Run mkdir -p ~/.claude/skills/summarize-changes
Why: A directory under ~/.claude/skills/ makes a personal skill that is available in your projects and invisible to teammates.
You should see: An empty summarize-changes directory in your personal skills folder.
2.Write SKILL.md in that directory, with a description saying it summarizes uncommitted changes, a body that injects !
git diff HEAD, and instructions to summarize the diff and list risks.Why: Claude uses the description to decide when to apply the skill, and the body is the prompt it follows.
You should see: A SKILL.md with YAML frontmatter followed by Markdown instructions.
3.In a repository with uncommitted edits, type /summarize-changes, then in a new session ask 'What did I change?'
Why: Shows both ways a skill can be triggered: by typing /name, or by Claude matching the description to your request.
You should see: Two or three bullet points summarizing the diff, followed by any risks.
4.Add context: fork to the frontmatter and invoke /summarize-changes again.
Why: Runs the skill in a forked subagent context, so only its summary comes back to your conversation.
You should see: The skill runs as a separate subagent, in the background by default, and returns a summary.
Stuck? Get a nudge
If the skill doesn't appear, check that the file is named exactly SKILL.md inside ~/.claude/skills/summarize-changes/.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/skillsOfficial docs
“Hint shown during autocomplete to indicate expected arguments.”
↩︎ Telling developers what to type: argument-hint“When no placeholder receives an argument, Claude Code appends them as ARGUMENTS: <value>.”
↩︎ Telling developers what to type: argument-hint“Claude uses this to decide when to apply the skill.”
↩︎ Telling developers what to type: argument-hint“Tools Claude can use without asking permission during the turn that invokes this skill.”
↩︎ allowed-tools pre-approves; disallowed-tools restricts“The grant clears when you send your next message.”
↩︎ allowed-tools pre-approves; disallowed-tools restricts“Claude Code honors the frontmatter in every kind of session, so an allowed-tools grant goes through the normal permission flow.”
↩︎ allowed-tools pre-approves; disallowed-tools restricts“Set to fork to run in a forked subagent context.”
↩︎ Isolating noisy skills with context: fork“The agent field determines the execution environment (model, tools, and permissions)”
↩︎ Isolating noisy skills with context: fork“Tools removed from Claude’s available pool while this skill is active.”
↩︎ Exam trap 1“Set to false to wait for the forked subagent’s result in the turn that invoked the skill”
↩︎ Exam trap 2“The subagent summarizes its results and returns them to your main conversation when it finishes”
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/features-overviewOfficial docs
“A side task floods your conversation with output you won’t reference again”
↩︎ Isolating noisy skills with context: fork