> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> How to contribute to Superpowers - skills, improvements, and bug fixes

# 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

<CardGroup cols={2}>
  <Card title="New Skills" icon="plus">
    Create skills for techniques, patterns, or tools you've found valuable
  </Card>

  <Card title="Skill Improvements" icon="arrow-up">
    Enhance existing skills with better examples, clearer explanations, or additional rationalizations
  </Card>

  <Card title="Bug Fixes" icon="bug">
    Fix issues in skills or the core system
  </Card>

  <Card title="Documentation" icon="book">
    Improve guides, examples, and reference material
  </Card>
</CardGroup>

## Before You Contribute

<Note>
  **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](/development/testing-skills) for details.
</Note>

### Required Reading

Before creating or modifying skills:

1. **Creating Skills** - Read [Creating Skills](/development/creating-skills) to understand skill structure and CSO
2. **Testing Skills** - Read [Testing Skills](/development/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

<Steps>
  <Step title="Fork the repository">
    Fork [obra/superpowers](https://github.com/obra/superpowers) to your GitHub account.

    ```bash theme={null}
    gh repo fork obra/superpowers --clone
    cd superpowers
    ```
  </Step>

  <Step title="Create a branch">
    Create a branch for your skill or improvement:

    ```bash theme={null}
    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
  </Step>

  <Step title="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](/development/testing-skills) for detailed methodology.
  </Step>

  <Step title="Document your testing">
    Create a test report showing:

    ```markdown theme={null}
    ## 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.
  </Step>

  <Step title="Commit your changes">
    Commit with clear, descriptive messages:

    ```bash theme={null}
    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."
    ```
  </Step>

  <Step title="Submit a pull request">
    Push your branch and create a PR:

    ```bash theme={null}
    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
    )"
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](https://github.com/obra/superpowers/discussions)
* **Bug reports**: Open an [Issue](https://github.com/obra/superpowers/issues)
* **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

* [Creating Skills](/development/creating-skills) - Complete skill creation guide
* [Testing Skills](/development/testing-skills) - Testing methodology
* [GitHub Repository](https://github.com/obra/superpowers) - Source code and issues
* [Marketplace](https://github.com/obra/superpowers-marketplace) - Plugin marketplace
* [Blog Post](https://blog.fsck.com/2025/10/09/superpowers/) - Philosophy and background