# Frontmatter Specification

Complete reference for SKILL.md YAML frontmatter fields.

## Required Fields

### `name`
- Lowercase-hyphen format: `my-skill-name`
- Max 64 characters
- Must be unique across all skill directories
- Becomes the slash command: `/my-skill-name`

### `description`
- One sentence, under 200 characters
- Should be slightly "pushy" — describe WHEN to use the skill, not just what it does
- Include trigger contexts so the model selects the skill proactively
- Good: "Scaffold a new React component with TypeScript, accessibility, all states, and variant support via cva."
- Bad: "Creates components."
- Pattern: `[Action verb] [what] — [key details]. Use when [trigger contexts].`

## Optional Fields

### `disable-model-invocation`
- `true` — skill only runs when user invokes via `/name`
- `false` (default) — model can auto-invoke when description matches user intent
- Project convention: always set to `true`

### `user-invocable`
- `true` (default) — appears as a slash command
- `false` — background knowledge only, used as reference by other skills

### `argument-hint`
- Shown in autocomplete: `/skill-name [hint]`
- Use brackets for placeholders: `"[file-or-directory]"`, `"[ComponentName]"`
- Omit if the skill takes no arguments

### `context`
- `fork` — runs in a forked context (separate conversation branch)
  - Use for: standalone deliverables, analysis reports, code generation that doesn't need follow-up
  - The skill gets its own clean context with only the skill instructions
- Omit (no fork) — runs in the main conversation context
  - Use for: interactive workflows, multi-step conversations, skills that need conversation history
  - When omitted, `agent` field should also be omitted

Decision tree:
1. Does the skill need conversation history? → no fork
2. Does the skill ask the user questions mid-flow? → no fork
3. Does the skill produce a single standalone output? → fork
4. Is it a one-shot analysis or generation? → fork

### `agent`
- Assigns a specialized agent persona. Only meaningful with `context: fork`.
- Available agents:

| Agent | Use for |
|---|---|
| `frontend-architect` | UI, components, CSS, accessibility, browser APIs |
| `backend-architect` | APIs, databases, server logic, system design |
| `code-reviewer` | Code review, quality analysis, diff review |
| `test-engineer` | Test writing, test strategy, coverage analysis |
| `security-auditor` | Security audit, threat modeling, vulnerability analysis |
| `prompt-engineer` | Prompt design, LLM configuration, prompt evaluation |
| `documentation-expert` | Documentation, ADRs, technical writing |

- Omit when: no fork, or skill doesn't fit a specific domain

### `allowed-tools`
- Restrict which tools the skill can use
- Comma-separated list: `allowed-tools: Read, Grep, Glob`
- Omit to allow all tools (default)

### `model`
- Override the model for this skill
- Example: `model: claude-sonnet-4-6`
- Omit to use the default model

### `hooks`
- Lifecycle event handlers (pre/post execution)
- Rarely needed for most skills

### `compatibility`
- Declare dependencies or requirements
- Example: `compatibility: node>=18`