Skill frontmatter & templating
This is the field reference for a SKILL.md file. For what a skill is and how
it’s discovered, used, and authored, see Skills — this
page is just the lookup tables.
Frontmatter keys
A SKILL.md opens with a YAML frontmatter block fenced by ---. Only
description is required; name defaults to the folder name; the rest are
optional. The in-app editor’s Insert key menu lists every recognized key:
![The "Insert key" dropdown from the skill editor. 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), 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).](/_astro/frontmatter-keys.DKQ3ajcv_ZbcNa1.webp)
| Key | Meaning |
|---|---|
description | Required. One sentence saying when to reach for the skill. It’s the only part always in front of the agent (and the text shown in the /skill picker), so it must earn the pull-in on its own. Up to 1024 characters. |
name | The skill’s id — a slug that must match the folder. Optional; when omitted, the folder name is used. Letters, digits, dots, underscores, hyphens; no spaces or slashes. Matched case-insensitively for uniqueness. |
disable-model-invocation | When true, the skill is left out of the agent’s automatic menu (<available_skills>) — the agent won’t pull it in on its own. Defaults to false. |
user-invocable | When true (the default), the skill can be invoked by hand with /skill:<name>. Set false to hide it from the / picker. |
argument-hint | A display-only hint shown in the picker, e.g. <topic> [depth]. |
arguments | Names for positional arguments, so the body can reference them as $name instead of $0, $1. A YAML list or a space-separated string. |
Templating tokens
The body is Markdown, but Brisal expands a few tokens when the skill runs — the editor shows them in a legend:
| Token | Expands to |
|---|---|
$ARGUMENTS | All trailing arguments after /skill:<name>. |
$N | The N-th positional argument, 0-based ($0 is the first). |
$name | A named positional alias, drawn from the arguments: list. |
$SRC_DIR | The current branch’s directory path. |
@path | A code reference to a file. |
@@path | Injects the contents of another file (a partial in the skill folder). |
!`cmd` | Runs a shell command inline; ```! fences a shell block. |
This is what makes a skill more than static text: it can take arguments, splice in sibling files, and pull live context from the working tree.
What to read next
- Skills — what a skill is, the four tiers, and how one gets used.
- Config files — the other hand-editable file format, theme palettes.