Use when creating new Claude Code skills or improving existing ones - ensures skills are discoverable, scannable, and effective through proper structure, CSO optimization, and real examples
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use when creating new Claude Code skills or improving existing ones - ensures skills are discoverable, scannable, and effective through proper structure, CSO optimization, and real examples
Creating Skills
Overview
Skills are reference guides for proven techniques, patterns, or tools. Write them to help future Claude instances quickly find and apply effective approaches.
Skills must be discoverable (Claude can find them), scannable (quick to evaluate), and actionable (clear examples).
Core principle: Default assumption is Claude is already very smart. Only add context Claude doesn't already have.
When to Use
Create a skill when:
Technique wasn't intuitively obvious
Pattern applies broadly across projects
You'd reference this again
Others would benefit
Don't create for:
One-off solutions specific to single project
Standard practices well-documented elsewhere
Project conventions (put those in .claude/CLAUDE.md)
Only name and description fields supported (max 1024 chars total)
Name: letters, numbers, hyphens only (max 64 chars). Use gerund form (verb + -ing)
Avoid reserved words: "anthropic", "claude" in names
Description: Third person, starts with "Use when..." (max 1024 chars)
Include BOTH triggering conditions AND what skill does
Match specificity to task complexity (degrees of freedom)
Document Structure
# Skill Name## Overview
Core principle in 1-2 sentences. What is this?
## When to Use- Bullet list with symptoms and use cases
- When NOT to use
## Quick Reference
Table or bullets for common operations
## Implementation
Inline code for simple patterns
Link to separate file for heavy reference (100+ lines)
## Common Mistakes
What goes wrong + how to fix
## Real-World Impact (optional)
Concrete results from using this technique
Degrees of Freedom
Match specificity to task complexity:
High freedom: Flexible tasks requiring judgment
Use broad guidance, principles, examples
Let Claude adapt approach to context
Example: "Use when designing APIs - provides REST principles and patterns"
Low freedom: Fragile or critical operations
Be explicit about exact steps
Include validation checks
Example: "Use when deploying to production - follow exact deployment checklist with rollback procedures"
Red flag: If skill tries to constrain Claude too much on creative tasks, reduce specificity. If skill is too vague on critical operations, add explicit steps.
Claude Search Optimization (CSO)
Critical: Future Claude reads the description to decide if skill is relevant. Optimize for discovery.
Description Best Practices
# ❌ BAD - Too vague, doesn't mention when to usedescription:Forasynctesting# ❌ BAD - First person (injected into system prompt)description:Ihelpyouwithflakytests# ✅ GOOD - Triggers + what it doesdescription:Usewhentestshaveraceconditionsorpass/failinconsistently-replacesarbitrarytimeoutswithconditionpollingforreliableasynctests# ✅ GOOD - Technology-specific with explicit triggerdescription:UsewhenusingReactRouterandhandlingauthredirects-providespatternsforprotectedroutesandauthstatemanagement
When: Reusable tools or multiple complete examples needed
With Heavy Reference
aws-sdk/
SKILL.md # Overview + workflows
s3-api.md # 600 lines API reference
lambda-api.md # 500 lines API reference
When: Reference material > 100 lines
Token Efficiency
Skills load into every conversation. Keep them concise.
Target Limits
SKILL.md: Keep under 500 lines
Getting-started workflows: <150 words
Frequently-loaded skills: <200 words total
Other skills: <500 words
Files > 100 lines: Include table of contents
Challenge each piece of information: "Does Claude really need this explanation?"
Compression Techniques
# ❌ BAD - Verbose (42 words)
Your human partner asks: "How did we handle authentication errors in React Router before?"
You should respond: "I'll search past conversations for React Router authentication patterns."
Then dispatch a subagent with the search query: "React Router authentication error handling 401"
# ✅ GOOD - Concise (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]
Techniques:
Reference tool --help instead of documenting all flags
Cross-reference other skills instead of repeating content
Show minimal example of pattern
Eliminate redundancy
Use progressive disclosure (reference additional files as needed)
Organize content by domain for focused context
Workflow Recommendations
For multi-step processes, include:
Clear sequential steps: Break complex tasks into numbered operations
Feedback loops: Build in verification/validation steps
Error handling: What to check when things go wrong
Checklists: For processes with many steps or easy-to-miss details
# ✅ GOOD - Name only with clear requirement**REQUIRED:** Use superpowers:test-driven-development before proceeding
**RECOMMENDED:** See typescript-type-safety for proper type guards
# ❌ BAD - Unclear if required
See skills/testing/test-driven-development
# ❌ BAD - Force-loads file, wastes context
@skills/testing/test-driven-development/SKILL.md
Advanced Practices
Iterative Development
Best approach: Develop skills iteratively with Claude
Start with minimal viable skill
Test with real use cases
Refine based on what works
Remove what doesn't add value
Build Evaluations First
Before extensive documentation:
Create test scenarios
Identify what good looks like
Document proven patterns
Skip theoretical improvements
Utility Scripts
For reliability, provide:
Scripts with explicit error handling (don't defer errors to Claude)
