Skill Format

Skills are defined in SKILL.md files with markdown content.

Directory Structure

.claude/skills/
└── my-skill/
    ├── SKILL.md           # Required: Skill definition
    └── references/        # Optional: Supporting files
        ├── example.md
        └── patterns.md

SKILL.md Format

# Skill Title

Instructions for Claude go here in markdown format.

## When to Use

Trigger conditions and context.

## Workflow

Step-by-step instructions.

Content Guidelines

The markdown content is your skill’s instructions to Claude.

Structure

1. Title - Clear skill name as H1
2. Quick Start - Essential info in the first few lines
3. When to Use - Trigger conditions
4. Main Content - Detailed instructions
5. Examples - Code or workflow examples
6. Notes - Caveats and edge cases

Writing Style

• Be direct and specific
• Use imperative mood (“Do this”, not “You should do this”)
• Include concrete examples
• Define blocking conditions if applicable
• Keep it concise (Claude has limited context)

Example Content

# Test-Driven Development

## Quick Start

Write failing test → Make it pass → Refactor. Never skip phases.

## Blocking Conditions

**BLOCKED: Cannot proceed until test failure is proven**

You must show test failure output before writing implementation code.

## Workflow

### Phase 1: RED
1. Write a test for expected behavior
2. Run the test - it MUST fail
3. Document failure output

### Phase 2: GREEN
1. Write minimal code to pass
2. Run test - it MUST pass
3. Document pass output

### Phase 3: REFACTOR
1. Clean up code
2. Tests must still pass

## Example Output

```
PHASE 1 - RED ✗
Test: should validate email format
Result: FAILED
Proceeding to Phase 2...
```

Supporting Files

Place additional resources in a references/ subdirectory:

my-skill/
├── SKILL.md
└── references/
    ├── api-patterns.md
    └── error-handling.md

Reference them from SKILL.md:

See [API Patterns](references/api-patterns.md) for detailed examples.

Tips

• Start with a working skill from the skills repo and modify it
• Test iteratively (Claude won’t follow vague instructions)
• Add blocking conditions for critical workflow steps
• Use tables for rationalizations Claude might try