Custom Skills

Overview

Create custom skills to extend Superpowers with project-specific patterns, tools, and best practices. Skills are reusable reference guides that help AI assistants apply effective approaches.

Skills ARE: Reusable techniques, patterns, tools, reference guides

Skills are NOT: Narratives about how you solved a problem once

Skill Directory Structure

skills/
└── my-skill/
    ├── SKILL.md           # Required: Main reference file
    └── supporting-file.*  # Optional: Supporting files (scripts, examples, etc.)

Directory Rules

• Flat namespace: All skills in one searchable namespace
• Separate files for:
  • Heavy reference material (100+ lines)
  • Reusable tools (scripts, templates)
• Keep inline:
  • Principles and concepts
  • Code patterns (< 50 lines)
  • Everything else

SKILL.md Format

Frontmatter (YAML)

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions and symptoms]
---

Field Reference:

Field	Required	Description
name	Yes	Skill name, letters/numbers/hyphens only (no parentheses/special chars)
description	Yes	When to use, starts with "Use when...", third person perspective

Important Rules:

• Total character limit: 1024 chars max
• description describes ONLY triggering conditions, don't summarize workflow
• Start with "Use when..." to focus on trigger conditions

Skill Types

Type	Description	Examples
Technique	Concrete method with steps to follow	condition-based-waiting, root-cause-tracing
Pattern	Way of thinking about problems	flatten-with-flags, test-invariants
Reference	API docs, syntax guides, tool documentation	office-docs

Document Structure Template

---
name: skill-name
description: Use when [specific triggering conditions]
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
- Specific symptoms and use cases
- When NOT to use

## Core Pattern
Before/after code comparison

## Quick Reference
Table or bullets for common operations

## Implementation
Inline code for simple patterns
Link to file for heavy reference

## Common Mistakes
What goes wrong + fixes

Naming Best Practices

Use Verb-First

✅ creating-skills    NOT skill-creation
✅ condition-based-waiting NOT async-test-helpers
✅ root-cause-tracing NOT debugging-techniques

Describe What You DO or Core Insight

✅ flatten-with-flags > data-structure-refactoring
✅ using-skills > skill-usage

Gerunds (-ing) Work Well for Processes

creating-skills, testing-skills, debugging-with-logs

Description Writing Tips

Key Principle: Description = When to Use, NOT What the Skill Does

# ❌ BAD: Summarizes workflow
description: Use when executing plans - dispatches subagent per task with code review

# ✅ GOOD: Only triggering conditions
description: Use when executing implementation plans with independent tasks

Content Requirements:

• Use concrete triggers, symptoms, and situations
• Describe the problem, not technology-specific symptoms
• Keep technology-agnostic unless skill itself is technology-specific
• Write in third person

# ❌ Too abstract
description: For async testing

# ✅ Describes problem
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

Search Optimization (CSO)

Help AI assistants find your skill:

1. Keyword Coverage

Use words AI would search for:

• Error messages: "Hook timed out", "race condition"
• Symptoms: "flaky", "hanging", "zombie"
• Synonyms: "timeout/hang/freeze"
• Tools: Actual commands, library names, file types

2. Token Efficiency

Target word counts:

• Getting-started workflows: < 150 words
• Frequently-loaded skills: < 200 words
• Other skills: < 500 words

Compression techniques:

• Use cross-references instead of repetition
• Compress examples to minimum
• Eliminate redundancy

Code Example Rules

One excellent example beats many mediocre ones

• Choose most relevant language
• Complete and runnable
• Comments explaining WHY
• From real scenario
• Ready to adapt

Don't:

• Implement in 5+ languages
• Create fill-in-the-blank templates
• Write contrived examples

Configuration File Locations

Platform	Built-in Skills	Custom Skills
Claude Code	~/.claude/plugins/superpowers/skills/	~/.claude/skills/
Cursor	~/.cursor/plugins/superpowers/skills/	~/.cursor/skills/
Codex	~/.codex/superpowers/skills/	~/.agents/skills/
OpenCode	~/.config/opencode/superpowers/skills/	~/.config/opencode/skills/

Creating a Skill Example

# Create skill directory
mkdir -p ~/.claude/skills/my-feature-workflow

# Create SKILL.md
cat > ~/.claude/skills/my-feature-workflow/SKILL.md << 'EOF'
---
name: my-feature-workflow
description: Use when implementing new features in this project
---

# My Feature Workflow

## Overview
Standard workflow for implementing features in this project.

## Process

1. **Design First**
   - Write spec document
   - Get approval before coding

2. **TDD Implementation**
   - Write failing test
   - Implement minimum code
   - Refactor

3. **Code Review**
   - Self-review checklist
   - Submit for team review

## Quick Reference

| Phase | Output |
|-------|--------|
| Design | `docs/specs/{feature}.md` |
| Tests | `tests/{feature}.test.ts` |
| Code | `src/{feature}/` |
EOF

Debugging Skills

Verify Skill is Recognized

# Check skills directory
ls ~/.claude/skills/

# Check SKILL.md format
head ~/.claude/skills/my-skill/SKILL.md

Common Issues

Skill not triggered:

• Check description clearly describes triggering conditions
• Ensure "Use when..." prefix
• Add more keywords

Skill content not followed:

• Reduce content length, increase density
• Use structured format (tables, lists)
• Add examples

Best Practices Summary

1. Naming: Verb-first, use hyphens
2. Description: Only triggering conditions, no workflow summary
3. Structure: Overview → When to Use → Pattern → Reference
4. Code: One excellent example
5. Length: Keep concise, < 500 words
6. Testing: Verify AI triggers correctly and follows instructions

Further Reference

For detailed skill authoring guidance, see Superpowers' writing-skills skill, including:

• TDD approach applied to documentation
• Pressure testing skills
• Bulletproofing against rationalization
• Complete checklist