# Quick Reference: Skills Best Practices

Fast checklist for skill development. See [best-practices.md](./best-practices.md) for detailed explanations.

## Skill Creation Checklist

### Structure

```
skill-name/
├── SKILL.md              # < 500 lines, core workflow
├── references/           # Deep dives (loaded on demand)
│   ├── patterns.md
│   ├── examples.md
│   └── advanced.md
└── scripts/              # Helper utilities
```

### SKILL.md Template

```markdown
---
name: kebab-case-name
description: What it does AND when to use it. Trigger terms: keywords, phrases.
version: 1.0.0
---

# Skill Name

<when_to_use>
Clear criteria for when this applies
</when_to_use>

<workflow>
1. Step one
2. Step two
3. Step three
</workflow>

<rules>
- ALWAYS: Do this
- NEVER: Don't do that
- PREFER: Recommended approach
</rules>

<references>
- [Pattern details](references/patterns.md)
- [Examples](references/examples.md)
</references>
```

## Description Checklist

- [ ] Third-person voice ("Creates reports" not "I create reports")
- [ ] Includes WHAT skill does
- [ ] Includes WHEN to use it
- [ ] Lists trigger terms users might say
- [ ] Under 100 tokens
- [ ] Specific, not generic

✅ **Good**: "Implements test-driven development using Red-Green-Refactor cycles. Use when implementing features with tests first, refactoring with test coverage, or reproducing bugs. Keywords: TDD, test-first, red-green-refactor."

❌ **Bad**: "Helps with testing"

## Common Mistakes to Avoid

| Mistake | Fix |
|---------|-----|
| Verbose SKILL.md (1000+ lines) | Keep under 500, move details to references/ |
| "NEVER do X" without alternatives | "ALWAYS do Y; NEVER do X" |
| Deeply nested references (3+ levels) | Keep 1 level deep with table of contents |
| No version control | Track in git with semantic versioning |
| No examples | Add 1-2 examples in references/examples.md |
| Unclear scope (skill does too much) | One skill, one job |
| Testing only with Sonnet | Test with Haiku, Sonnet, AND Opus |
| Static text without action | Make it executable/testable |

## Testing Checklist

### Before Publishing

- [ ] Test with Haiku (needs more explicit instructions?)
- [ ] Test with Sonnet (balanced clarity?)
- [ ] Test with Opus (handles complexity?)
- [ ] Use skill for real work (dogfooding)
- [ ] Check description triggers discovery correctly
- [ ] Verify workflow completes successfully
- [ ] Review security (no malicious code)
- [ ] Under 500 lines in SKILL.md
- [ ] References properly linked

### Ongoing Validation

- [ ] Track skill load frequency
- [ ] Monitor completion rate
- [ ] Log user satisfaction
- [ ] Note when Claude asks for clarification (skill unclear?)
- [ ] Build regression tests for critical paths

## Composition Patterns

### Reference Other Skills

```markdown
Load the **outfitter:debugging** skill using the Skill tool to investigate.
```

### Skill Chaining

```markdown
1. Load **pathfinding** skill for planning
2. Load **tdd** skill for implementation
3. Load **code-review** skill for validation
```

### Skills + MCP

- **MCP**: Data access (APIs, databases, tools)
- **Skill**: Workflows (what to do with that data)

## Progressive Disclosure

```
Discovery (50 tokens)      → YAML frontmatter
   ↓
Activation (2-5K tokens)   → SKILL.md core
   ↓
Execution (dynamic)        → references/ loaded on demand
```

**Key**: Don't load everything upfront. Let Claude request detail.

## Degrees of Freedom

| Level | Format | When to Use |
|-------|--------|-------------|
| **High** | Text instructions | Creative tasks, multiple valid approaches |
| **Medium** | Pseudocode | Standard patterns with variation allowed |
| **Low** | Scripts | Security-critical, exact sequence required |

**Examples:**

| Task | Freedom |
|------|---------|
| Error message formatting | High |
| API integration | Medium |
| Authentication flows | Low |
| Database migrations | Low |
| Code formatting | High |

## Security Quick Check

- [ ] Review all scripts in scripts/ directory
- [ ] No credential harvesting (API keys, tokens)
- [ ] No unexpected file system writes
- [ ] No suspicious network requests
- [ ] No obfuscated code
- [ ] Verify external dependencies
- [ ] Test in isolated environment first

## Description Optimization Formula

```
[What it does] + [When to use] + [Trigger keywords]
```

**Example**:
"Debugs issues using systematic root cause analysis. Use when encountering errors, unexpected behavior, or test failures. Keywords: debug, troubleshoot, error, failure, bug."

## Versioning Rules

- **MAJOR** (1.0.0 → 2.0.0): Breaking changes (workflow changed, different inputs)
- **MINOR** (1.0.0 → 1.1.0): New features (additional optional steps)
- **PATCH** (1.0.0 → 1.0.1): Bug fixes (typos, clarifications)

## One-Liners to Remember

1. **Assume intelligence** - Claude doesn't need basic concepts explained
2. **Be directive, not comprehensive** - Focus on what makes THIS approach different
3. **One skill, one job** - Don't make Swiss Army knife skills
4. **Test like code** - Build evals, use version control, review changes
5. **Progressive disclosure** - Start small, load detail on demand
6. **Security matters** - Skills execute code; review carefully
7. **Positive constraints** - Tell what TO do, not just what NOT to do
8. **Examples clarify** - Non-obvious patterns need concrete examples
9. **Version semantically** - Breaking changes = major version bump
10. **Dogfood relentlessly** - Use your own skills for real work

## Advanced Patterns Quick List

- **Degrees of freedom**: Match instruction specificity to task type
- **Solve don't punt**: Scripts should handle errors, not fail to Claude
- **Variant organization**: Multi-framework skills with selection in SKILL.md
- **Hook-based validation**: PreToolUse for quality gates
- **Master-Clone architecture**: Preserve context via subagents
- **Eval-driven development**: Tests before extensive docs
- **Organization-wide libraries**: Central skill registry
- **Skills as living docs**: Replace static wikis
- **Conditional chaining**: Orchestrate complex workflows
- **ToC in references**: Navigate to specific sections (>100 lines)
- **Skill contribution flow**: Treat like open source PRs

See [patterns.md](./patterns.md) for detailed examples.

## When to Create a Skill vs Other Tools

| Need | Use |
|------|-----|
| Multi-step workflow with judgment | **Skill** |
| Simple shortcut/expansion | Slash command |
| Data access / API integration | MCP server |
| Specialized autonomous work | Subagent |
| Event-triggered automation | Hook |

## Getting Help

- **Official docs**: <https://platform.claude.com/docs/en/agents-and-tools/agent-skills>
- **Community**: ComposioHQ/awesome-claude-skills (GitHub)
- **Research**: skillmatic-ai/awesome-agent-skills (GitHub)
- **Examples**: Load existing well-crafted skills for patterns

Last updated: 2026-01-10