AI_template/.claude/skills/create-skill/references/frontmatter-spec.md

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