← Docs

Skill frontmatter & templating

This page is the field reference for SKILL.md. For the conceptual overview, see Skills.

Frontmatter keys

A SKILL.md starts with a YAML frontmatter block between ---. Only description is required; name defaults to the folder name; the rest are optional.

The skill editor with its "Insert key" dropdown open, listing every recognized key in two groups. Under "Known keys": name (Slug key, must match folder), description (Shown in /skill picker + system prompt), disable-model-invocation (Hide from <available_skills>), user-invocable (Allow /skill:name invocation), disable-substitution (Serve files verbatim — no @@/!/$ expansion), argument-hint (Picker hint, e.g. <topic> [depth]), arguments (Named positional argument aliases). Under "Reserved — not yet enforced": context (Delegation context, fork | fresh), agent (Delegation agent reference), allowed-tools (Tool allowlist, no consumer yet), disallowed-tools (Tool denylist, no consumer yet).

KeyMeaning
descriptionRequired. One sentence stating when to use the skill. Always visible to the agent and shown in the /skill picker — must justify the skill on its own. Max 1024 chars.
nameSkill id — a slug that must match the folder name. Optional; defaults to folder name. Letters, digits, dots, underscores, hyphens; no spaces/slashes. Case-insensitive uniqueness.
disable-model-invocationWhen true, excludes the skill from the agent’s <available_skills> menu — the agent won’t auto-load it. Default: false.
user-invocableWhen true (default), allows /skill:<name> invocation. Set false to hide from the / picker.
disable-substitutionWhen true, serves files verbatim — templating tokens (@@, !`cmd`, $ARGUMENTS, etc.) are not evaluated. Default: false. For reference skills that document token syntax.
argument-hintDisplay-only hint shown in picker, e.g. <topic> [depth].
argumentsNames for positional arguments, letting the body reference them as $name instead of $0, $1. YAML list or space-separated string.

Templating tokens

The body is Markdown with token expansion. The editor shows these in a legend:

TokenExpands to
$ARGUMENTSAll trailing arguments after /skill:<name>.
$NN-th positional argument, 0-based ($0 is first).
$nameNamed positional alias from arguments:.
$SRC_DIRCurrent branch’s directory path.
@pathCode reference to a file.
@@pathInjects another file’s contents from the skill folder.
!`cmd`Runs a shell command inline; ```! fences a shell block.

These tokens make skills dynamic: they can take arguments, splice in files, and pull live context. To serve text verbatim (e.g., for token documentation), set disable-substitution: true.

  • Skills — what a skill is, the four tiers, and usage.
  • Config files — other hand-editable formats, theme palettes.