v10/.claude/skills/create-skill/references/structure.md

Skill Structure

Complete reference for skill structure and frontmatter.

Frontmatter Schema

Required Fields

Field	Type	Description
name	string	Skill identifier. Used with skill tool. Kebab-case, lowercase.
description	string	When to use and trigger phrases. This is the PRIMARY mechanism for skill selection — Claude only sees this before deciding to load.

Optional Fields

Field	Type	Default	Description
context	fork	—	Creates isolated sub-agent context. Use for command skills that run autonomously.
allowed-tools	string	all	Restricts available tools. Format: Tool1, Tool2, Bash(cmd:*). Use for command skills.
agent	plan	—	Sets agent to plan/research mode. Agent cannot make edits, only read and analyze.
disable-model-invocation	boolean	false	Prevents skill from invoking other models. Use for skills that should only provide guidance.

Description Best Practices

# ❌ Too brief — won't trigger correctly
description: Component patterns

# ❌ Triggers in body — won't work (body loads AFTER triggering)
description: Component patterns
---
## When to Use
Use this skill when building components...

# ✅ Complete — triggers included
description: >-
  Build accessible, headless UI components with modern architecture patterns.
  Use when creating component libraries, design systems, or reusable UI primitives.
  Handles compound components, state management, accessibility, styling hooks.
  Triggers: "create component", "component architecture", "compound component".

Directory Structure

Minimal (Command/Simple Workflow)

skill-name/
└── SKILL.md

Use for: Simple commands, straightforward workflows.

Examples: commit-pr, claude-update

With References (Knowledge/Complex Workflow)

skill-name/
├── SKILL.md
└── references/
    ├── topic-a.md
    ├── topic-b.md
    └── topic-c.md

Use for: Domain expertise, detailed patterns, multiple topics.

Examples: api, component, aria

With Templates (Output-Focused)

skill-name/
├── SKILL.md
├── references/
└── templates/
    ├── output-type-a.md
    ├── output-type-b.md
    └── output-type-c.md

Use for: Skills that produce structured outputs (docs, RFCs, etc.).

Examples: docs, rfc

With Review Capability

skill-name/
├── SKILL.md
├── references/
└── review/
    ├── workflow.md      # Review process, when to use
    ├── checklist.md     # Quick single-agent checklist
    ├── templates.md     # Output formats for issues/reports
    └── agents.md        # Sub-agent prompts (if multi-agent)

Use for: Skills that can review existing code/content.

Examples: api, component, aria, docs

SKILL.md Structure

Knowledge Skill Template

---
name: skill-name
description: >-
  Domain description. Use when X, Y, Z.
  Triggers: "phrase1", "phrase2", "phrase3".
---

# Skill Title

Brief overview (1-2 sentences).

## Quick Reference

Most important patterns/rules in condensed form.

## Reference Files

| File | Contents |
|------|----------|
| [references/topic-a.md](references/topic-a.md) | Description |
| [references/topic-b.md](references/topic-b.md) | Description |

## Review

For reviewing X, load `review/workflow.md`.

## Related Skills

| Need | Use |
|------|-----|
| Related domain | `other-skill` skill |

Command Skill Template

---
name: skill-name
description: >-
  What command does. Triggers: "phrase1", "phrase2".
allowed-tools: Tool1, Tool2, Bash(cmd:*)
context: fork
---

# Command Name

Brief description of what the command does.

## Usage

\`\`\`
/skill-name [args]
\`\`\`

- `arg` (optional/required): Description

## Arguments

$ARGUMENTS

## Your Tasks

### Step 1: Task Name

Instructions...

### Step 2: Task Name

Instructions...

## Important

- Key constraint 1
- Key constraint 2

Workflow Skill Template

---
name: skill-name
description: >-
  Workflow description. Triggers: "phrase1", "phrase2".
context: fork
---

# Workflow Name

Brief overview.

## Reference Material

| Task | Load |
|------|------|
| Task type A | `references/a.md` |
| Task type B | `references/b.md` |

## Quick Reference

Key conventions in condensed form.

## Process

1. Step one
2. Step two
3. Step three

Naming Conventions

Element	Convention	Example
Skill directory	kebab-case	create-skill/
Skill name	kebab-case	create-skill
Reference files	kebab-case	anti-patterns.md
Template files	kebab-case	component-page.md

Tool Restriction Patterns

# Git and GitHub only
allowed-tools: Bash(git:*), Bash(gh:*), Glob, Grep, Read, mcp__github__*

# Read-only exploration
allowed-tools: Glob, Grep, Read

# File creation allowed
allowed-tools: Bash(mkdir:*), Glob, Grep, Read, Write, Edit

# With user interaction
allowed-tools: Bash(git:*), Glob, Grep, Read, question