skill-crafting

What this skill does

# Skill Crafting

Create effective, discoverable skills that work under pressure.

## When to Use

**Creating:**
- "Create a skill for X"
- "Build a skill to handle Y"

**From Session History:**
- "Create a skill from this session"
- "Turn what we just did into a skill"
- "Can the database setup we did become a skill?"
- "Could we create a skill from this?" (evaluate first)
- "Should this be a skill?" (evaluate first)

**Fixing:**
- "This skill isn't working"
- "Why isn't this skill triggering?"
- "Skill didn't trigger when it should have"

**Analyzing:**
- "Analyze my skill for issues"
- "Run skill analysis"
- "Check this skill's quality"
- "Audit all my skills"
- "Check character budget across skills"

## Analyzing a Skill

When user asks to analyze a skill:

1. **Run scripts first when available** for mechanical checks:
   ```bash
   python3 scripts/analyze-all.py path/to/skill/
   ```

   If scripts fail because of environment or tooling issues, state the blocker clearly and continue with manual review.

2. **Read the skill files** for qualitative review:
   - Read SKILL.md
   - Read REFERENCES.md (if exists)
   - Read directly linked `references/`, `scripts/`, or `agents/openai.yaml` files when they materially affect behavior

3. **Provide holistic feedback** covering:
   - Script results (CSO, structure, tokens) or explicit blocker if scripts could not run
   - Does `allowed-tools` match what the skill needs to do?
   - Does the analysis cover the files that actually define the skill's behavior?
   - Is the workflow clear and actionable?
   - Are references appropriate and sized correctly?
   - Missing sections or anti-patterns?

4. **Give verdict** with prioritized recommendations

## Validation Scripts

| Script | Purpose | Usage |
|--------|---------|-------|
| `analyze-all.py` | Run all checks | `python3 scripts/analyze-all.py path/to/skill/` |
| `analyze-cso.py` | Check CSO compliance | `python3 scripts/analyze-cso.py path/to/SKILL.md` |
| `analyze-tokens.py` | Count tokens | `python3 scripts/analyze-tokens.py path/to/SKILL.md` |
| `analyze-triggers.py` | Find missing triggers | `python3 scripts/analyze-triggers.py path/to/SKILL.md` |
| `check-char-budget.py` | Check 15K limit | `python3 scripts/check-char-budget.py path/to/skills/` |

**Quick start:**
```bash
python3 scripts/analyze-all.py ~/.claude/skills/my-skill/
python3 scripts/check-char-budget.py ~/.claude/skills/
```

## Creating from Current Session

When user asks to create a skill from the current session:

1. **Reflect on the conversation** — you already have full context
2. **Assess skill-worthiness** using criteria below
3. **If worthy**: Generate SKILL.md using methodology in this skill
4. **If not**: Explain why (one-off, too scattered, etc.)

### Skill-Worthiness Criteria

| Question | ✅ Extract | ❌ Skip |
|----------|-----------|---------|
| Will this repeat? | 3+ future uses likely | One-off task |
| Non-trivial? | Multi-step coordination | Just "read, edit" |
| Domain knowledge? | Captures expertise | Generic actions |
| Generalizable? | Works across projects | Project-specific |

### Quick Assessment

Before creating, answer:
1. **What pattern repeats?** (e.g., "set up auth with tests")
2. **What would break without the skill?** (steps someone might skip)
3. **Who else would use this?** (just me? team? public?)

If you can't answer these clearly → probably not skill-worthy.

### For Evaluative Questions

When user asks "could this be a skill?" or "any reusable patterns?":

1. Review what you did in this session
2. Identify distinct workflow segments (not exploration/debugging)
3. Apply criteria above
4. Recommend yes/no with specific reasoning
5. If partial: suggest which part is worth extracting

## Core Principle

**Writing skills is TDD for documentation.**

1. **RED**: Test without skill → document failures
2. **GREEN**: Write skill addressing those failures
3. **REFACTOR**: Close loopholes, improve discovery

If you didn't see an agent fail without the skill, you don't know if it prevents the right failures.

## Skill Types

| Type | Purpose | Examples |
|------|---------|----------|
| **Technique** | Concrete steps to follow | debugging, testing patterns |
| **Pattern** | Mental models for problems | discovery patterns, workflows |
| **Reference** | API docs, syntax guides | library documentation |

## Structure

### Minimal Skill (Single File)

```
skill-name/
└── SKILL.md
```

### Multi-File Skill

```
skill-name/
├── SKILL.md              # Overview (<500 lines)
├── references/           # Docs loaded as needed
│   └── api.md
├── scripts/              # Executable code
│   └── helper.py
└── assets/               # Templates, images
    └── template.html
```

### SKILL.md Anatomy

```yaml
---
name: skill-name          # required, lowercase + hyphens, <64 chars
description: "..."        # required, <1024 chars, trigger clauses only
allowed-tools: Read Bash(python:*)  # optional, Claude Code extension
context: fork             # optional, Claude Code extension (isolated subagent)
---

# Skill Name

## When to Use
[Triggers and symptoms]

## Workflow
[Core instructions]

## Recovery
[When things go wrong]
```

## Claude Search Optimization (CSO)

**The description field determines if your skill gets discovered.**

### Description Rules

1. **Include one or more "Use when..." clauses** — focus on triggers
2. **Include specific symptoms** — exact words users say
3. **Write in third person** — injected into system prompt
4. **NEVER summarize the workflow** — causes Claude to skip reading the skill

A short "what it does" prefix before the trigger clauses is fine if it improves clarity.

**Good:**

```yaml
description: "GitHub operations via gh CLI. Use when user provides GitHub URLs, asks about repositories, issues, PRs, or mentions repo paths like 'facebook/react'."
```

**Bad:**

```yaml
description: "Helps with GitHub"  # Too vague
description: "I can help you with GitHub operations"  # First person
description: "Runs gh commands to list issues and PRs"  # Summarizes workflow
```

### Why No Workflow Summary?

Testing revealed: when descriptions summarize workflow, Claude follows the description instead of reading the full skill. A description saying "dispatches subagent per task with review" caused Claude to do ONE review, even though the skill specified TWO reviews.

**Description = When to trigger. SKILL.md = How to execute.**

### Keyword Coverage

Include words Claude would search for:

- Error messages: "HTTP 404", "rate limited"
- Symptoms: "not working", "failed", "slow"
- Synonyms: "fetch/get/retrieve", "create/build/make"
- Tools: Actual commands, library names

## Writing Effective Skills

### Concise is Key

Context window is shared. Every token competes.

**Default assumption: AI is already very smart.**

Only add context the AI doesn't have:

- ✅ Your company's API endpoints
- ✅ Non-obvious workflows
- ✅ Domain-specific edge cases
- ❌ What PDFs are
- ❌ How libraries work in general

### Progressive Disclosure

Three-level loading:

1. **Metadata** (name + description) — Always loaded (~100 words)
2. **SKILL.md body** — Loaded when triggered (<500 lines)
3. **Bundled resources** — Loaded as needed (unlimited)

Keep SKILL.md lean. Move details to reference files.

### Set Appropriate Freedom

| Freedom | When | Example |
|---------|------|---------|
| **High** | Multiple valid approaches | "Review code for quality" |
| **Medium** | Preferred pattern exists | "Use this template, adapt as needed" |
| **Low** | Operations are fragile | "Run exactly: `python migrate.py --verify`" |

### Discovery Over Documentation

Don't hardcode what changes. Teach discovery instead.

**Brittle (will break):**

```markdown
gh issue list --repo owner/repo --state open
```

**Resilient (stays current):**

```markdown
1. Run `gh issue --help` to see available commands
2. Apply discovered syntax to request
```

## Testing Skills

### Why Test?

Skills that enforce discipl