ea21818f76
Two modes: Create (gather requirements, generate SKILL.md) and Improve (diagnose existing skill against best practices, propose changes). Includes bundled references for frontmatter spec and writing guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
84 lines
3.1 KiB
Markdown
84 lines
3.1 KiB
Markdown
# 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`
|