The SKILL.md Frontmatter Reference
Everything You Can Configure
The Markdown body holds instructions, but the YAML frontmatter is where you control a skill's behavior. All fields are optional — only description is recommended. Here's a frontmatter using the most common controls:
---
name: my-skill
description: What this skill does and when to use it.
allowed-tools: Read, Grep, Glob
disable-model-invocation: true
---
Your skill instructions here...The Core Fields
| Field | Purpose |
|---|---|
| name | Display label in skill listings (defaults to the directory name) |
| description | What it does + when to use it — drives matching (recommended) |
| when_to_use | Extra trigger phrases / example requests, appended to description |
| allowed-tools | Tools pre-approved when the skill is active (no per-use prompt) |
| model | Model to use while the skill is active (or 'inherit') |
| argument-hint | Autocomplete hint for expected arguments, e.g. [issue-number] |
The fields you'll reach for most. description is the one that matters for matching.
Description length cap
A skill's description (combined with when_to_use) is truncated at 1,536 characters in the skill listing to limit context usage. Put your key use case FIRST so the critical keywords survive any trimming.
Invocation & Execution Control
Several fields control WHO can invoke a skill and WHERE it runs — we'll go deeper on these in later lessons, but here's the map:
- •disable-model-invocation: true — only YOU can invoke it (via /name); Claude won't trigger it automatically. Good for side-effect workflows like /deploy.
- •user-invocable: false — only CLAUDE can invoke it; hidden from the / menu. Good for background knowledge.
- •context: fork — run the skill inside a forked subagent (isolated context).
- •agent — which subagent type to use when context: fork is set (Explore, Plan, general-purpose, or a custom one).
- •paths — glob patterns that limit when the skill auto-activates (e.g. only on test files).
Two fields control invocation: disable-model-invocation makes a skill manual-only; user-invocable: false makes it Claude-only.
Arguments and Substitution
Skills accept arguments and support string substitution, so you can parameterize them. Declare named arguments with the arguments field, and reference values in the body with placeholders.
| Placeholder | Expands to |
|---|---|
| $ARGUMENTS | All arguments passed to the skill |
| $ARGUMENTS[N] or $N | The Nth argument (0-based), e.g. $0, $1 |
| $name | A named argument declared in the 'arguments' frontmatter |
| ${CLAUDE_SKILL_DIR} | The skill's own directory (use for script paths) |
| ${CLAUDE_SESSION_ID} | The current session ID |
String substitutions let one skill handle many inputs — e.g. /fix-issue 123 puts 123 into $ARGUMENTS.
Next
The description field does the heavy lifting for matching. The next lesson is dedicated to writing descriptions that trigger reliably on the right requests.
Key Takeaways
- ✓SKILL.md frontmatter controls behavior; all fields are optional, only description is recommended.
- ✓Core fields: name (display label, defaults to directory), description (matching), when_to_use (extra triggers), allowed-tools (pre-approved tools), model, argument-hint.
- ✓Description + when_to_use is capped at 1,536 chars in the listing — put the key use case first.
- ✓Invocation control: disable-model-invocation: true (you-only), user-invocable: false (Claude-only); execution: context: fork + agent (run as a subagent); paths (limit auto-activation by file globs).
- ✓Skills accept arguments via $ARGUMENTS, $ARGUMENTS[N]/$N, and named $name placeholders.
- ✓Useful built-in substitutions include ${CLAUDE_SKILL_DIR} (for script paths) and ${CLAUDE_SESSION_ID}.
Check Your Understanding
Test what you learned in this lesson.
Q1.Which frontmatter field makes a skill manual-only (Claude won't auto-trigger it)?
Q2.What does the allowed-tools field do?
Q3.Why should a skill's key use case go first in the description?
Q4.How do you reference all arguments passed to a skill in its body?
Practice This Lesson