Contributing Skills

Relevant source files

• .claude-plugin/marketplace.json
• .claude-plugin/plugin.json
• RELEASE-NOTES.md
• agents/code-reviewer.md
• skills/finishing-a-development-branch/SKILL.md
• skills/using-git-worktrees/SKILL.md
• skills/writing-skills/SKILL.md
• skills/writing-skills/render-graphs.js

This page covers the process for contributing new skills to the shared skill library at obra/superpowers-skills. It covers repository setup, readiness requirements, and the pull request workflow.

For details on writing a new skill from scratch (the TDD cycle, pressure scenarios, and checklist), see Creating Skills. For the file format and frontmatter specification, see SKILL.md Format and Structure.

---

Two Repositories, One Contribution Target

The superpowers project uses a dual-repository layout. Skills are contributed to the skills repository, not the plugin repository. See Dual Repository Design for full details.

Repository	URL	What changes here
obra/superpowers	Plugin code, hooks, platform integrations	Bug fixes to bootstrap, hook, tool mapping
obra/superpowers-skills	All SKILL.md files and supporting assets	New skills, skill edits, supporting files

A contribution adding or modifying a skill targets obra/superpowers-skills. A contribution fixing the Claude Code session hook targets obra/superpowers.

Sources: RELEASE-NOTES.md578-603

---

Readiness Gate

Before opening a pull request, the full TDD cycle for the skill must be complete. The Skill Creation Checklist and the deployment section of writing-skills define readiness explicitly.

The relevant deployment items from skills/writing-skills/SKILL.md626-633 are:

- [ ] Commit skill to git and push to your fork (if configured)
- [ ] Consider contributing back via PR (if broadly useful)

A skill is ready to contribute when all checklist phases pass:

• RED phase — baseline scenario run without the skill; agent violations documented
• GREEN phase — skill written and verified with agent; compliance confirmed
• REFACTOR phase — loopholes closed, rationalization table built, red flags listed

Do not open a PR for a skill that has not passed pressure scenario testing. Untested skills introduce regressions in agent behavior for all users.

Sources: skills/writing-skills/SKILL.md596-633

---

Contribution Workflow

The contribution process follows a standard fork-branch-PR model.

Contribution flow diagram:

Sources: RELEASE-NOTES.md578-603 skills/writing-skills/SKILL.md626-633

---

Skill Directory Layout in the PR

Every skill must live in a named subdirectory under skills/. The directory name becomes the skill's namespace identifier (e.g., superpowers:my-skill).

skills/
  my-skill/
    SKILL.md              # Required. Contains YAML frontmatter + content.
    supporting-file.*     # Optional. Only if needed (heavy reference, reusable scripts).

The name field in SKILL.md frontmatter must match the directory name, using only letters, numbers, and hyphens.

Key constraints on the frontmatter:

Field	Constraint
name	Letters, numbers, hyphens only — no parentheses or special characters
description	Max 1024 characters total; must start with "Use when..."
Total frontmatter	Only name and description are supported fields

Sources: skills/writing-skills/SKILL.md93-137

---

What Belongs in a Skill PR vs. Other Changes

Code entity to repository mapping:

Sources: .claude-plugin/plugin.json1-13 RELEASE-NOTES.md578-590

---

PR Content Guidelines

When opening a pull request, include the following in the PR description:

Section	Content
What the skill teaches	One sentence describing the agent behavior change
When it triggers	The specific conditions described in the description field
Pressure scenarios tested	Summary of RED phase scenarios and which pressures were used
Baseline behavior	What agents did without the skill (verbatim rationalizations are useful)
Post-skill behavior	What agents do with the skill present
Loopholes closed	Any REFACTOR iterations and the rationalizations they addressed

The PR reviewer will assess:

• Whether the skill solves a problem that cannot be automated via tooling (mechanical constraints should be automated, not documented — see skills/writing-skills/SKILL.md56-59)
• Whether the description field triggers only on conditions, not on workflow summary (the "Description Trap" from Claude Search Optimization (CSO))
• Whether the Iron Law was followed: no skill created without a failing baseline first

---

Skill Scope: Broadly Useful vs. Personal

Not every skill belongs in the shared library. The decision tree:

From skills/writing-skills/SKILL.md50-59:

Create when:

• Technique wasn't intuitively obvious to you
• You'd reference this again across projects
• Pattern applies broadly (not project-specific)
• Others would benefit

Don't create for:

• One-off solutions
• Standard practices well-documented elsewhere
• Project-specific conventions (put in CLAUDE.md)
• Mechanical constraints (if it's enforceable with regex/validation, automate it)

Sources: skills/writing-skills/SKILL.md50-59

---

Historical Note: sharing-skills Skill

Prior to v4.0.0, a standalone sharing-skills skill guided the contribution workflow. It was removed in v4.0.0 as obsolete after the workflow was consolidated into writing-skills and the deployment checklist. See RELEASE-NOTES.md287-290:

Skill consolidation — sharing-skills removed (obsolete)

The current authoritative source for the contribution deployment steps is the writing-skills skill at skills/writing-skills/SKILL.md626-633

Sources: RELEASE-NOTES.md285-292