Create Skill

Skills are markdown files that provide domain-specific knowledge to AI assistants. They load on-demand (unlike CLAUDE.md which always loads), enabling progressive disclosure of detailed information.

When to Create a Skill

Create a skill when:

• •A domain has enough complexity to warrant its own documentation
• •You find yourself repeatedly explaining the same patterns
• •Code examples and troubleshooting steps would help

Don't create a skill when:

• •The information fits in CLAUDE.md (stable, always-needed info)
• •The domain is too small (just add it to an existing skill or CLAUDE.md)

Directory Structure

.claude/skills/
└── <skill-name>/
    ├── SKILL.md           # Required: overview, when to use
    └── reference.md       # Highly recommended: code examples

• •Use lowercase with hyphens for directory names
• •SKILL.md is required - overview and key concepts
• •reference.md is highly recommended - keeps code examples separate and scannable
• •Name should describe the domain or workflow

Why reference.md is Recommended

Separating overview from code examples:

• •Keeps SKILL.md concise and readable
• •Makes code patterns easy to find and copy
• •Scales better as the skill grows
• •Agents can read just what they need

Only skip reference.md when:

• •The skill is purely conceptual (no code)
• •You have fewer than 3 short code snippets

File Format

Every skill starts with YAML frontmatter:

---
name: skill-name
description: One sentence describing what this skill covers
---

Followed by markdown content:

# Skill Title

Brief intro explaining the scope.

## Section

Content with examples, patterns, instructions...

Content Guidelines

Include:

• •Overview of the domain/workflow
• •Code examples specific to your project's stack
• •Step-by-step instructions for common tasks
• •Troubleshooting for known issues
• •Links to related files in the codebase

Avoid:

• •Generic information easily found in official docs
• •Duplicating content from CLAUDE.md
• •Overly long explanations (be concise)

Effective Sections

Pick sections that fit your skill's domain:

Skill Size

• •No strict limit, but aim for focus over breadth
• •A skill can be 50 lines or 200 lines depending on complexity
• •If a skill grows too large, consider splitting into multiple skills

Template

Copy this template to create a new skill:

---
name: {{skill-name}}
description: {{One sentence description}}
---

# {{Skill Title}}

{{Brief intro paragraph explaining scope.}}

## Overview

{{Key concepts and context.}}

## Patterns

{{Code examples with explanation.}}

\`\`\`{{language}}
// Example code
\`\`\`

## Common Tasks

### {{Task Name}}

1. {{Step 1}}
2. {{Step 2}}
3. {{Step 3}}

## Troubleshooting

### {{Issue}}

**Symptoms:** {{What the user sees}}

**Solution:** {{How to fix it}}

## Related Files

- `{{path/to/file}}` - {{description}}

reference.md Template

If your skill needs detailed code examples, create reference.md:

# {{Skill Name}} Reference

Detailed code examples and patterns.

## {{Pattern Category}}

### {{Pattern Name}}

{{When to use this pattern.}}

\`\`\`{{language}}
{{code example}}
\`\`\`

## API Examples

### {{Endpoint/Function}}

\`\`\`{{language}}
{{request/response or usage example}}
\`\`\`

## Schema / Types

\`\`\`typescript
{{type definitions}}
\`\`\`

## Configuration

\`\`\`{{format}}
{{config example}}
\`\`\`

Link to it from SKILL.md:

## Reference Files

- [reference.md](reference.md) - Code examples and patterns

Referencing Skills

After creating a skill, add it to the skills list in CLAUDE.md so users know it exists:

## Skills

Domain-specific knowledge lives in `.claude/skills/`:
- `create-skill/` - How to create new skills
- `your-new-skill/` - Description of your skill