The frontmatter fields that matter most
| Field | What it does |
|---|---|
description / when_to_use | What the skill does and when Claude should use it |
disable-model-invocation: true | Only you can invoke it, and it stays out of Claude's context until you do. Use it for side effects like /deploy. |
user-invocable: false | Only Claude can invoke it, hidden from the / menu. Good for background knowledge. |
allowed-tools | Pre-approves listed tools while the skill runs, so fewer prompts |
context: fork | Runs the skill in its own subagent context |
model / effort | Override the model or effort level for the turn |
paths | Globs that limit when the skill activates automatically |
argument-hint | Autocomplete hint, such as [issue-number] |
A skill that deploys, publishes, sends messages or deletes things should have disable-model-invocation: true. You don't want Claude deciding on its own that now feels like a good time to deploy.
Progressive disclosure: layers of detail
Keep SKILL.md focused (well under 500 lines) and move depth into supporting files that Claude reads only when needed:
.claude/skills/pdf-reports/
├── SKILL.md # overview + when to read each file
├── reference.md # full style guide (read for layout questions)
├── examples.md # 3 finished reports (read before drafting)
└── scripts/
└── render.sh # executed, never loaded into contextIn SKILL.md, tell Claude when to open each file:
For layout and typography rules, read [reference.md](reference.md).
Before drafting, skim [examples.md](examples.md) for tone.
To produce the PDF, run `scripts/render.sh <input.md>`. Don't reimplement it.Scripts: deterministic power at zero context cost
Scripts in a skill are executed, not read into context. A 300-line validation script costs nothing until it runs, and then only its output enters the conversation. Pre-approve it so it runs without a prompt:
---
name: pdf-reports
description: Build branded PDF reports from markdown. Use when the user asks for a report or PDF.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---${CLAUDE_SKILL_DIR} resolves to the skill's own folder, so the path works wherever the skill is installed.
Dynamic context: inject live data
A line starting with ` !command ` runs before Claude sees the skill, and its output is inlined:
## Current state
- Branch: !`git branch --show-current`
- Uncommitted files: !`git status --porcelain | wc -l`Claude starts the skill already knowing the facts, with no extra tool calls.
Forked skills
context: fork runs the skill in an isolated subagent. Heavy work (reading dozens of files, a long audit) happens in a separate context, and only the result returns to your main conversation. Pair it with agent: to choose which subagent type runs it.
Check your understanding
Which field should a /deploy skill almost always have?
How do bundled scripts affect context?
What does ` !git branch --show-current ` do in a SKILL.md?
Why keep SKILL.md short and link to reference files?