skill-builder

# Skill Builder

Build production-quality Skills for Claude Code with proper structure, discoverable descriptions, and best practices.

## Quick Reference

**Description Formula**: `[What it does] + [When to use it] + [Trigger terms users say]`

**Name Rules**: Lowercase letters, numbers, hyphens only; max 64 characters; no spaces

**Description Rules**: Max 1024 characters; must be specific with trigger terms

## The Skill Creation Workflow

### Phase 1: Requirements Gathering

Use AskUserQuestion to understand what they need:

1. **What should the Skill do?**
   - What capability or expertise should it provide?
   - What tasks should it help with?

2. **When should it activate?**
   - What scenarios or contexts?
   - What words/phrases would users say?
   - What file types or operations?

3. **Scope decision**
   - Personal Skill (~/.claude/skills/) - just for this user
   - Project Skill (.claude/skills/) - shared with team via git

4. **Structure complexity**
   - Single file (simple instructions/examples)
   - Multi-file (scripts, templates, extensive docs)

5. **Tool restrictions**
   - Full access (default)
   - Restricted (allowed-tools field for read-only or limited scope)

### Phase 2: Description Crafting

The description determines discoverability. Use this proven formula:

```
[Specific operations] + [When to use] + [Trigger terms]
```

**Example walkthrough**:
- ❌ "Helps with documents" (too vague)
- ✅ "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction."

**Key elements**:
1. **Specific operations**: List concrete actions (extract, analyze, generate, validate)
2. **When to use**: Scenarios and contexts (when working with X, during Y, for Z tasks)
3. **Trigger terms**: Exact words users would say (PDF, forms, commit message, data analysis)

See [examples/descriptions.md](examples/descriptions.md) for more patterns.

### Phase 3: Name Validation