6.8 KiB

Raw Permalink Blame History

Quick Reference: Skills Best Practices

Fast checklist for skill development. See 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

---
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

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

Skill Chaining

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

Assume intelligence - Claude doesn't need basic concepts explained
Be directive, not comprehensive - Focus on what makes THIS approach different
One skill, one job - Don't make Swiss Army knife skills
Test like code - Build evals, use version control, review changes
Progressive disclosure - Start small, load detail on demand
Security matters - Skills execute code; review carefully
Positive constraints - Tell what TO do, not just what NOT to do
Examples clarify - Non-obvious patterns need concrete examples
Version semantically - Breaking changes = major version bump
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 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

6.8 KiB Raw Permalink Blame History