Skip to main content

​
Contributing to Superpowers

Superpowers is built on community contributions. Whether you’re creating new skills, improving existing ones, or fixing bugs, your contributions help make coding agents more effective for everyone.

​
What You Can Contribute

New Skills

Create skills for techniques, patterns, or tools you’ve found valuable

Skill Improvements

Enhance existing skills with better examples, clearer explanations, or additional rationalizations

Bug Fixes

Fix issues in skills or the core system

Documentation

Improve guides, examples, and reference material

​
Before You Contribute

All skills must follow the TDD approach. Before contributing a skill, you must test it with subagents following the RED-GREEN-REFACTOR cycle. See Testing Skills for details.

​
Required Reading

Before creating or modifying skills:
  1. Creating Skills - Read Creating Skills to understand skill structure and CSO
  2. Testing Skills - Read Testing Skills to learn the testing methodology
  3. writing-skills SKILL.md - Read skills/writing-skills/SKILL.md in the repository for complete guidance

​
Contribution Guidelines

  • Follow TDD: Test skills with subagents before submitting
  • One skill per PR: Makes review easier and faster
  • Document testing: Include test scenarios and baseline results
  • Follow naming conventions: Use verb-first, active voice names
  • Optimize for search: Use CSO best practices
  • Keep it concise: Target word counts for token efficiency

​
The Contribution Process

1

Fork the repository

Fork obra/superpowers to your GitHub account.
gh repo fork obra/superpowers --clone
cd superpowers
2

Create a branch

Create a branch for your skill or improvement:
git checkout -b skill/your-skill-name
Branch naming:
  • skill/skill-name for new skills
  • improve/skill-name for skill improvements
  • fix/issue-description for bug fixes
  • docs/topic for documentation
3

Create and test your skill

Follow the complete TDD cycle:
  1. RED Phase: Run baseline tests without the skill
    • Document agent behavior
    • Capture rationalizations verbatim
    • Identify patterns in failures
  2. GREEN Phase: Write the minimal skill
    • Address specific baseline failures
    • Add rationalization table
    • Include clear examples
    • Test with skill loaded
  3. REFACTOR Phase: Close loopholes
    • Capture new rationalizations
    • Add explicit counters
    • Re-test until bulletproof
See Testing Skills for detailed methodology.
4

Document your testing

Create a test report showing:
## Test Report: [skill-name]

### Baseline Tests (RED)

**Scenario 1**: [description]
- Pressure: [type of pressure]
- Baseline behavior: [what agent did]
- Rationalizations: [verbatim quotes]

**Scenario 2**: [description]
...

### With Skill (GREEN)

**Scenario 1**: ✅ Agent complied
**Scenario 2**: ✅ Agent complied

### Refactor Iterations

**Iteration 1**:
- New rationalization: [quote]
- Counter added: [description]
- Re-test: ✅ Complies

### Final Results

All scenarios pass with no new rationalizations.
Include this in your PR description or as a comment.
5

Commit your changes

Commit with clear, descriptive messages:
git add skills/your-skill-name/
git commit -m "Add [skill-name] skill for [purpose]

Addresses [specific problem].
Tested with [number] pressure scenarios.
All baseline tests show compliance."
6

Submit a pull request

Push your branch and create a PR:
git push origin skill/your-skill-name
gh pr create --title "Add [skill-name] skill" --body "$(cat <<'EOF'
## Summary

[Brief description of the skill and problem it solves]

## Testing

- ✅ RED phase: Baseline tests completed
- ✅ GREEN phase: Skill addresses baseline failures
- ✅ REFACTOR phase: Loopholes closed
- ✅ [Number] pressure scenarios tested

## Checklist

- [ ] Follows writing-skills SKILL.md guidelines
- [ ] CSO optimized (descriptive name, keywords, rich description)
- [ ] Tested with subagents (RED-GREEN-REFACTOR)
- [ ] Rationalization table included
- [ ] One excellent example (not multi-language)
- [ ] Token-efficient (<500 words for normal skills)

## Test Results

[Include test report or link to test documentation]
EOF
)"
7

Address review feedback

Maintainers may request:
  • Additional test scenarios
  • Clarification of examples
  • CSO improvements
  • Token efficiency improvements
Respond to feedback and update your PR accordingly.

​
Skill Contribution Checklist

Before submitting a PR, verify: Structure:
  • Name uses letters, numbers, hyphens only
  • YAML frontmatter with name and description (under 1024 chars)
  • Description starts with “Use when…” and includes triggers only
  • Clear overview with core principle
  • Quick reference table
  • Common mistakes section
  • One excellent example
CSO (Claude Search Optimization):
  • Descriptive, verb-first name
  • Rich description with concrete triggers
  • Keywords throughout (errors, symptoms, tools)
  • Description in third person
  • No workflow summary in description
Testing:
  • RED phase completed (baseline tests)
  • GREEN phase completed (skill addresses failures)
  • REFACTOR phase completed (loopholes closed)
  • 3+ pressure scenarios tested (for discipline skills)
  • Rationalization table included
  • Test report documented
Quality:
  • Token-efficient (under 500 words for normal skills)
  • No narrative storytelling
  • No multi-language examples
  • Flowcharts only if decision non-obvious
  • Supporting files only for tools/heavy reference

​
Code of Conduct

​
Our Standards

Positive behaviors:
  • Using welcoming and inclusive language
  • Being respectful of differing viewpoints and experiences
  • Gracefully accepting constructive criticism
  • Focusing on what is best for the community
  • Showing empathy towards other community members
Unacceptable behaviors:
  • Trolling, insulting/derogatory comments, and personal attacks
  • Public or private harassment
  • Publishing others’ private information without permission
  • Other conduct which could reasonably be considered inappropriate

​
Our Responsibilities

Project maintainers are responsible for clarifying standards of acceptable behavior and will take appropriate and fair corrective action in response to any instances of unacceptable behavior.

​
Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team through GitHub issues. All complaints will be reviewed and investigated promptly and fairly.

​
Types of Contributions

​
New Skills

When creating a new skill:
  1. Verify it’s needed: Check existing skills for overlap
  2. Follow TDD: Complete RED-GREEN-REFACTOR cycle
  3. Test thoroughly: 3-5 scenarios minimum
  4. Document testing: Include test report in PR
Good candidates for new skills:
  • Techniques you’ve found valuable across projects
  • Patterns that aren’t intuitively obvious
  • Tools with complex workflows
  • Reference material not well-documented elsewhere
Not good candidates:
  • One-off solutions
  • Highly project-specific approaches
  • Duplicate of existing skills
  • Standard practices well-documented elsewhere

​
Skill Improvements

When improving existing skills:
  1. Test current version: Run baseline to understand current behavior
  2. Identify gaps: What rationalizations does current skill miss?
  3. Add counters: Address specific gaps found in testing
  4. Re-test: Verify improvements work
Good improvements:
  • Adding rationalizations from real usage
  • Better examples
  • Clearer explanations
  • CSO optimization
  • Token efficiency improvements

​
Bug Fixes

When fixing bugs:
  1. Reproduce the issue: Understand the problem
  2. Test the fix: Verify it solves the problem
  3. Document the fix: Explain what was broken and how you fixed it
  4. Check for regressions: Ensure fix doesn’t break other scenarios

​
Review Process

What to expect:
  1. Initial review (1-3 days): Maintainer checks structure and testing
  2. Testing verification (2-5 days): Maintainer may run additional tests
  3. Feedback (as needed): Requests for changes or clarification
  4. Approval (after changes): PR approved and merged
Timeline: Most PRs are reviewed within a week. Complex skills or improvements may take longer.

​
Questions?

If you have questions about contributing:
  • General questions: Open a Discussion
  • Bug reports: Open an Issue
  • Contribution questions: Comment on the relevant PR or issue

​
Recognition

Contributors are recognized in:
  • Commit history
  • Release notes
  • README acknowledgments (for significant contributions)
Thank you for helping make Superpowers better for everyone!

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us