Skip to main content

Skill Frontmatter

The frontmatter is the block of keys at the top of a SKILL.md file. It sets the name, the description, the tools the skill may use, and who may call it. For example, disable-model-invocation: true makes a skill that only you can start.

Use disable-model-invocation and user-invocable, or the skillOverrides setting, to turn a skill off.

Example​

.claude/skills/review/SKILL.md
---
name: review
description: Review the current branch for bugs.
when_to_use: Use when the user asks for a code review.
argument-hint: "[path]"
allowed-tools: Read Grep Glob
model: inherit
effort: high
context: fork
agent: general-purpose
paths:
  - "src/**"
---

Review the changes under $ARGUMENTS and list the bugs you find.

Rules​

  • Claude Code reads the frontmatter only when the first line is ---.
  • A YAML error loads the skill with no fields. You see the warning [skills] YAML frontmatter ... failed to parse and was ignored.
  • Keys are case-sensitive. Claude Code ignores an unknown key with no error.
  • Booleans accept true, false, yes, no, on, off, 1, and 0 in any case (2.1.218 or later).
  • A top-level PreToolUse or PermissionRequest key outside hooks is an error. The skill then loads with no hooks and no allowed-tools.
  • If description is missing, Claude Code uses the first line of the body. It removes heading marks and cuts the text at 100 characters.

Keys​

KeyStatusWhat it doesNotes
name
Documented: An official docs page names this item.
The command name.Defaults to the folder name. At most 256 characters. Skills and plugin skills only, not command files.
description
Documented: An official docs page names this item.
Tells Claude when to use the skill.Numbers and booleans become strings. The listing cuts it at 1,536 characters.
when_to_use
Documented: An official docs page names this item.
More trigger text.Claude Code adds it after description. Counts toward the 1,536 limit. The only documented key with an underscore.
argument-hint
Documented: An official docs page names this item.
An autocomplete hint.Text, for example [issue-number].
arguments
Documented: An official docs page names this item.
Names for $name placeholders.A space-separated string or a YAML list. Claude Code drops names made only of digits.
disable-model-invocation
Documented: An official docs page names this item.
Stops Claude from loading the skill by itself.Also blocks preload into subagents and use by scheduled tasks.
user-invocable
Documented: An official docs page names this item.
false hides the skill from the / menu.Default true.
allowed-tools
Documented: An official docs page names this item.
Tools allowed without a prompt for the turn.A space or comma string, or a list. The grant clears at your next message. Ignored under allowManagedPermissionRulesOnly (2.1.282). Since 2.1.305, plugins that Claude Desktop mounts by path no longer keep their allowed-tools when your organization's managed settings set it (v2.1.305 release). ${CLAUDE_SKILL_DIR} works in Bash rules.
disallowed-tools
Documented: An official docs page names this item.
Removes tools while the skill is active.The same format. The program also reads disallowedTools.
model
Documented: An official docs page names this item.
The model for the turn.inherit keeps the active model. A model outside availableModels is not used. With context: fork it sets the subagent model.
effort
Differs: The official docs and the program disagree. The row says how. Docs: low, medium, high, xhigh, max. The program also accepts an integer.
The effort level for the turn.The program warns Valid options: ... or an integer.
context
Documented: An official docs page names this item.
fork runs the skill in a subagent.Claude Code ignores any other value.
agent
Documented: An official docs page names this item.
The subagent type for context: fork.Default general-purpose.
background
Documented: An official docs page names this item.
false waits for the forked result.Default true. 2.1.218 or later.
hooks
Documented: An official docs page names this item.
Hooks that start when the skill runs.They last for the session. See Hooks.
paths
Documented: An official docs page names this item.
A glob limit for automatic loading.Claude Code removes a trailing /**. A list of only ** means no limit. Skills only.
shell
Documented: An official docs page names this item.
The shell for !`cmd` blocks.bash or powershell. Other values cause a warning. Claude Code then uses bash.
metadata
Documented: An official docs page names this item.
A free map for your own tools.Claude Code drops it when it is not a map.
license
Documented: An official docs page names this item.
An Agent Skills spec field.Claude Code accepts it. It has no effect.
compatibility
Documented: An official docs page names this item.
An Agent Skills spec field.A string up to 500 characters. No effect.
version
Documented: An official docs page names this item.
Skill version text.Claude Code reads it as a string. Not in the docs key table. For skills and plugin commands.
fallback
Documented: An official docs page names this item.
A boolean that the loader reads.The loader parses it with the boolean rule above.
created_by, improved_by
Undocumented: Only the program shows this item. It can change without notice.
Mark a skill as made by the dream-proposal flow.Only the value dream-proposal counts. The env var CLAUDE_CODE_SKILL_PROPOSALS exists.
experimental
Documented: An official docs page names this item.
Experimental: The program or the official docs call this experimental or beta.
A map. Claude Code records its key names.Only the key names go into declaredFields.

Skill Discovery with Bash cd​

Since 2.1.312, Claude Code finds per-directory skills and paths skills after a Bash command moves the working directory deeper into the same git repository. When a file is read or written, the program walks up from the file to a base directory. It looks for .claude/skills on the way. It also tests the paths globs of conditional skills against the file path, relative to that base. The base is now the directory where the session started, when all of these are true:

  • The working directory is not the directory where the session started.
  • The working directory is inside that directory.
  • Both directories are in the same git repository.

In any other case, the base is the working directory. For a file outside the working directory, the program skips a .claude/skills folder that git ignores or that it cannot confirm. Source: the program (chunk-r5cyd28m.js lines 156298 to 156312 and 156113 to 156170).

Outside Claude Code​

claude.ai uploads and the Skills API accept only name, description, license, compatibility, metadata, and allowed-tools. Other keys fail the upload.

Exact Fields​

The exact fields are in the skill definition in https://clawdipedia.cc/schemas/claude-code-frontmatter.json. It comes from the program's frontmatter validators. It lists every field of this release. Build on the fields that it names. Look each one up there before you rely on it.

Source: Extend Claude with Skills, Settings Reference, and the program (the frontmatter parser).