skill-development

# Skill Development

Create effective Claude Code skills that are concise, discoverable, and well-structured.

## Quick Reference

You MUST read these references for detailed guidance:

- [Best Practices](./references/best-practices.md) - Official Anthropic guidance
- [Skill Examples](./references/examples.md) - Patterns from real skills

## Core Principles

1. **Concise is key** - Only add context Claude doesn't already have
2. **Progressive disclosure** - SKILL.md is the overview; details go in `references/`
3. **Write in third person** - "This skill processes..." not "I can help you..."

## Skill Structure

```
skill-name/
├── SKILL.md              # Main instructions (< 500 lines)
└── references/           # Detailed docs (loaded on demand)
    ├── guide.md
    └── examples/
```

## YAML Frontmatter

```yaml
---
name: my-skill-name
description: This skill should be used when the user asks to "do X", "create Y", or mentions Z. Be specific about triggers.
context: fork          # Optional: run in isolated context (prevents side effects)
user-invocable: true   # Optional: show in slash command menu (default: true)
---
```

**Name rules:**
- Lowercase letters, numbers, hyphens only
- Max 64 characters
- No reserved words (anthropic, claude)

**Description rules:**
- Max 1024 characters
- Third person ("This skill..." not "I can...")
- Include WHAT it does AND WHEN to use it

**Optional fields:**
- `context: fork` - Run skill in isolated sub-agent context, preventing unintended side effects on main agent state
- `user-invocable: false` - Hide from slash command menu (skills are visible by default)

## Writing Effective Descriptions

Include trigger phrases the user might say:

```yaml
# Good - specific triggers
description: This skill should be used when the user asks to "create a hook", "add a hook", or mentions Claude Code hooks.

# Bad - vague
description: Helps with automation tasks.
```

## Progressive Disclosure Pattern

Keep SKILL.md under 500 lines. Link to d