Frontmatter Options Reference

Frontmatter Options Reference

Complete reference for auditing skill and command frontmatter. Load this before running Dimension 2 audits. Every field listed here is the full set of valid options — anything not on this list is not a valid frontmatter key.

Fields

name (string)

Lowercase letters, digits, and hyphens only. Max 64 characters. Omit to use the directory name as the identifier. Prefer short, verb-led names for commands. Namespace by tool when it aids routing clarity: gh-address-comments, linear-close-issue.

description (string)

The primary triggering mechanism. Always in context — costs tokens on every session regardless of whether the skill is active. Use > folded scalar (not | literal). Must be third-person for skills ("This skill should be used when..."), verb-first under 60 chars for commands.

model (enum)

Audit rule: opus is only justified when the task genuinely requires deep reasoning that sonnet would struggle with. Most skills should omit model: entirely and inherit. haiku is underused — prefer it for lookup-heavy, low-judgment steps.

context (enum)

Use context: fork when: the skill produces heavy output that would pollute the main conversation context; the skill needs clean separation from conversation history; the skill delegates to a specialized agent via agent:. Requires agent: to be set.

agent (string)

Requires context: fork. Routes execution to a specialized agent type.

allowed-tools (list)

Restricts which tools the skill can use. Default is unrestricted. Specifying this list is a security and scope constraint — use it to limit blast radius for sensitive skills.

Complete tool list:

Audit rule: Bash unrestricted is almost always wrong — scope it. AskUserQuestion must be present if the skill asks the user anything. Skill must be present if the skill invokes another skill by name.

Tool Selection Framework

The core principle: restrict tools that have destructive or side-effect potential, not tools that are read-only or purely generative. Over-restriction breaks the skill; under- restriction is a security and scope risk.

Gap audit questions:

• Does the skill need user decisions but lacks AskUserQuestion? → add it
• Does the skill invoke another skill but lacks Skill? → add it
• Does the skill write files but has no Edit or Write? → add them
• Does the skill have unrestricted Bash when a scoped pattern would work? → scope it
• Does the skill have Bash(git:*) but never uses git? → remove it (dead scope)

hooks (object)

Scoped to this skill's lifecycle. Runs scripts before or after specific tool events.

hooks:
  PreToolUse:
    - command: "scripts/validate-input.sh"
  PostToolUse:
    - command: "scripts/cleanup.sh"
  Stop:
    - command: "scripts/on-complete.sh"

Valid hook events: PreToolUse, PostToolUse, Stop. Use for validation, logging, side effects, or cleanup that must happen deterministically around tool calls.

user-invocable (boolean)

Use false for background-knowledge skills that should activate automatically but shouldn't clutter the command menu.

disable-model-invocation (boolean)

Commands only. Prevents Claude from auto-loading this skill based on its description. Forces manual invocation only. Default: false.

argument-hint (string)

Shown in autocomplete when the user types the command. Documents expected argument syntax. Examples: "[issue-number]", <path-to-skill>, "[skill|command] [name]".

Quoting rule: values that contain [...] must be quoted ("[arg]"), because YAML treats unquoted [ as the start of a flow sequence. Values using only <...> do not need quoting.

Audit rule: any skill that reads $ARGUMENTS or $1/$2 should have argument-hint set so users know what to pass.

Dynamic Content Syntax

These substitutions are processed before the skill body reaches Claude.

Audit rule: skills that accept a file path as input should use @$1 to load it inline rather than requiring a separate Read tool call — the injection happens before the model sees the skill, saving a tool round-trip. The bang-backtick pattern is underused: real-time data like git branch, file tree, or env vars can be injected without tool calls.