Skip to main content

​
Overview

Skills live directly in the Superpowers repository. Contributing one back means it becomes available to every user who installs the plugin — automatically, with no extra setup required on their end. Before submitting, your skill must be written following the writing-skills skill and tested using the methodology in Testing Skills. Untested skills that don’t hold up under pressure will be asked to revise before merging.

​
Contribution steps

1

Fork the repository

Fork github.com/obra/superpowers on GitHub, then clone your fork locally:
git clone https://github.com/YOUR-USERNAME/superpowers.git
cd superpowers
2

Create a branch for your skill

Use a descriptive branch name that matches your skill’s directory name:
git checkout -b skill/my-skill-name
3

Write the skill following the writing-skills guide

Create a directory for your skill under skills/:
mkdir skills/my-skill-name
Then create skills/my-skill-name/SKILL.md with valid YAML frontmatter and a Markdown body. Follow the complete process in Writing Skills, including the TDD methodology:
  1. Run baseline scenarios without the skill (RED)
  2. Write the skill addressing those specific failures (GREEN)
  3. Close loopholes discovered in testing (REFACTOR)
If your skill needs supporting reference files, place them in the same directory.
4

Test your skill

Run pressure scenarios with a subagent to verify the skill triggers at the right time and holds up under pressure. See Testing Skills for the complete methodology.Document the rationalizations you encountered and how you addressed them — reviewers will look for evidence of testing.
5

Submit a pull request

Push your branch and open a PR against the main Superpowers repository:
git add skills/my-skill-name/
git commit -m "Add my-skill-name skill"
git push origin skill/my-skill-name
Then open a PR on GitHub with a description that explains:
  • What the skill does and when it triggers
  • What baseline failures you observed before writing it
  • How you tested it and what pressure scenarios you used

​
PR checklist

Before submitting, verify each of the following: Frontmatter:
  • name field matches the directory name exactly
  • name uses only letters, numbers, and hyphens (no parentheses or special characters)
  • description starts with “Use when…” and describes only triggering conditions — no workflow summary
  • description is written in third person
  • Both fields are present and within character limits (name: 64 chars, description: 1024 chars)
Content:
  • Skill is tested with pressure scenarios using the RED-GREEN-REFACTOR cycle
  • Baseline failures are documented and addressed in the skill body
  • No placeholder text, TBDs, or incomplete sections
  • Consistent terminology throughout
  • Examples are concrete, not abstract
Organization:
  • Supporting reference files (if any) are in the skill directory
  • File references from SKILL.md are one level deep — no nested reference chains
  • File names are descriptive
  • No Windows-style backslash paths
Scope:
  • Skill is broadly useful across projects (project-specific conventions belong in CLAUDE.md)
  • Skill teaches something not intuitively obvious or not documented elsewhere

​
Code of Conduct

All contributors are expected to follow the Contributor Covenant Code of Conduct. The short version:
  • Demonstrate empathy and kindness toward other people
  • Be respectful of differing opinions, viewpoints, and experience levels
  • Give and gracefully accept constructive feedback
  • Focus on what is best for the community
Unacceptable behavior includes harassment, trolling, personal attacks, and publishing others’ private information. Violations can be reported to [email protected].

​
Sharing without a PR

Not every skill needs to be in the main repository. You can share skills through the Superpowers Marketplace at github.com/obra/superpowers-marketplace — a community registry for skills that are useful but outside the core library’s scope. The marketplace is also a good place to publish skills that are specific to a particular tool, framework, or workflow before deciding whether to propose them for the main library.

​
Getting help

If you’re unsure whether a skill is ready to submit, or want feedback before opening a PR:

Writing Skills

How to write a skill from scratch

Testing Skills

Verify your skill before submitting

Build docs developers (and LLMs) love

Get started for freeTalk to us