# The SKILL.md Reference: Every Frontmatter Field Explained

> A complete reference for the SKILL.md format — all frontmatter fields, naming rules, argument substitution, limits, and where skill files live.

A SKILL.md is YAML frontmatter plus a Markdown body. Only name and description are required, but the full field set is larger than most posts document: triggering controls (when_to_use, paths, disable-model-invocation), execution controls (allowed-tools, model, effort, context: fork), argument plumbing, and distribution metadata from the open Agent Skills spec.

Most write-ups of the SKILL.md format stop at `name`, `description`, and `allowed-tools`. The actual field set is roughly twice that size. This is the field-by-field reference, current as of July 2026, drawn from the Claude Code docs and the open Agent Skills specification (agentskills.io). If you're new to skills, start with [What Are Claude Skills?](/guides/skills/what-are-claude-skills) — this page assumes you know why you're writing one.

## The file

```text
.claude/skills/<name>/
├── SKILL.md          # required
├── scripts/          # optional, loaded only when referenced
└── references/       # optional, same
```

`SKILL.md` is YAML frontmatter between `---` fences, then a Markdown body. The body is the procedure; the frontmatter is everything below.

## Required fields

| Field | Rules |
|---|---|
| `name` | Max 64 chars. Lowercase letters, numbers, hyphens only. Must match the parent directory name — the directory is what defines the `/name` invocation. |
| `description` | What the skill does **and** when to use it. Spec cap: 1,024 chars. This is the only text Claude sees until the skill fires, so it carries the entire triggering decision. |

```yaml
---
name: release-notes
description: Draft user-facing release notes from merged PRs since the last tag.
  Use when cutting a release or asked to write release notes or a changelog.
---
```

## Triggering fields

These control *when* the skill activates:

| Field | Default | What it does |
|---|---|---|
| `when_to_use` | — | Extra trigger context (example phrasings, situations) appended to the description in the skill listing. The combined text is budgeted to ~1,536 chars — front-load what matters. |
| `paths` | — | Glob patterns (string or list). The skill auto-activates only when the task involves matching files — e.g. `paths: "migrations/**"` keeps a migration skill quiet everywhere else. |
| `disable-model-invocation` | `false` | `true` = Claude can never auto-invoke it; only your explicit `/name` runs it. Use for deploy runbooks and anything destructive. Also keeps the skill out of subagents. |
| `user-invocable` | `true` | `false` = hidden from the `/` menu; the skill exists purely as background knowledge Claude applies when relevant. |

## Execution fields

These control *how* the skill runs once triggered:

| Field | Default | What it does |
|---|---|---|
| `allowed-tools` | — | Tools Claude may use **without asking**, only during the turn that invoked the skill; the grant clears on your next message. String or list; supports scoped forms like `Bash(git diff:*)`. Friction reduction, not sandboxing. Ignored by the Agent SDK (use its own `allowedTools`). |
| `disallowed-tools` | — | The restrictive counterpart: tools removed from Claude's pool while the skill is active. Same turn-scoped duration. |
| `model` | session model | Run this skill on a specific model (same values as `/model`). Reverts to the session model on your next prompt. |
| `effort` | session effort | Override reasoning effort for this skill: `low` through `max`. A mechanical formatting skill can run at `low` while your session stays at `high`. |
| `context` | — | `context: fork` runs the skill in an isolated subagent context instead of the main conversation — the skill's reading and tool calls never touch your main window. Requires a body that's an explicit task, not passive guidelines. |
| `agent` | `general-purpose` | With `context: fork`: which subagent executes it — `Explore`, `Plan`, `general-purpose`, or a custom agent from `.claude/agents/`. |
| `shell` | `bash` | Shell used for inline `` !`command` `` output injection in the body: `bash` or `powershell`. |
| `hooks` | — | Hooks scoped to this skill's lifecycle — fire on events only while the skill runs, instead of registering globally in settings. See [Claude Code hooks](/guides/configuration/claude-code-hooks). |

## Argument fields

Skills invoked as `/name arg1 arg2` receive their arguments in the body:

| Field | What it does |
|---|---|
| `argument-hint` | Autocomplete hint shown in the `/` menu — e.g. `[issue-number]` or `[filename] [format]`. |
| `arguments` | Declares **named** positional arguments (space-separated string or list), so the body can use `$name` instead of `$1`. |

In the body: `$ARGUMENTS` is everything passed, `$0`/`$1`/`$ARGUMENTS[N]` index individual (shell-quoted) arguments, and named variables come from the `arguments` declaration:

```markdown
---
name: fix-issue
description: Fix a GitHub issue by number. Use when asked to fix issue #N.
arguments: issue
argument-hint: "[issue-number]"
---

Fetch issue #$issue with `gh issue view $issue`, reproduce it, fix it, and
reference "Fixes #$issue" in the commit message.
```

## Distribution fields (open spec)

From the agentskills.io standard — metadata for sharing, read by any conforming tool:

| Field | What it does |
|---|---|
| `license` | License name or a pointer to a bundled file: `"Apache-2.0"`, or `"Proprietary — see LICENSE.txt"`. |
| `metadata` | Arbitrary key-value map for client-specific extensions; no standard keys. |
| `compatibility` | Max 500 chars describing environment requirements (target product, required packages, network access). Most skills omit it. |

> [!NOTE]
> **No `version` field.** It appears in older examples around the web, but it's not in the spec, and clients ignore it. Version at the distribution layer instead: [plugin](/guides/skills/packaging-and-sharing-skills) releases, git tags, or the epoch-stamped version IDs the Claude API assigns on `/v1/skills`.

## Where skill files live

| Scope | Path | Notes |
|---|---|---|
| Personal | `~/.claude/skills/<name>/SKILL.md` | Follows you across all projects |
| Project | `.claude/skills/<name>/SKILL.md` | Checked in, shared with the team |
| Nested (monorepo) | `packages/*/.claude/skills/` | Qualified as `/dir:name` when names collide |
| Plugin | `<plugin>/skills/<name>/SKILL.md` | Namespaced as `/plugin:name` |
| Enterprise | Managed by org admins | Distributed org-wide via managed settings |

Changes are picked up live — adding or editing a SKILL.md takes effect in the current session, no restart. If a skill and a legacy `.claude/commands/` file share a name, the skill wins.

## Limits cheat sheet

- `name`: 64 chars, `[a-z0-9-]`, must equal the folder name
- `description`: 1,024 chars (spec); combined with `when_to_use`, ~1,536 chars shown in the listing before truncation
- `compatibility`: 500 chars
- Tool grants and restrictions (`allowed-tools`/`disallowed-tools`): duration is the invoking turn only
- Claude API requests: max 8 skills attached per request, 30 MB per uploaded skill

For how these fields behave outside Claude Code — claude.ai upload, the `/v1/skills` API, the Agent SDK — see [Claude Skills on claude.ai and the API](/guides/skills/claude-skills-on-claude-ai-and-api).

---

_Source: https://agentscamp.com/guides/skills/skill-md-reference — Guide on AgentsCamp._