MCPInstall

sharing skills

Contribute skills back to upstream via branch and PR

Installs
502
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/obra/superpowers-skills --skill sharing-skills
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads sharing skills automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Sharing Skills

Overview

Contribute skills from your local branch back to the upstream repository.

Workflow: Branch → Edit/Create skill → Commit → Push → PR

When to Share

Share when:

  • Skill applies broadly (not project-specific)
  • Pattern/technique others would benefit from
  • Well-tested and documented
  • Follows skills/meta/writing-skills guidelines

Keep personal when:

  • Project-specific or organization-specific
  • Experimental or unstable
  • Contains sensitive information
  • Too narrow/niche for general use

Prerequisites

  • gh CLI installed and authenticated
  • Working directory is ~/.config/superpowers/skills/ (your local clone)
  • Skill has been tested (see skills/meta/writing-skills for TDD process)

Sharing Workflow

1. Ensure You're on Main and Synced

cd ~/.config/superpowers/skills/
git checkout main
git pull upstream main
git push origin main  # Push to your fork

2. Create Feature Branch

# Branch name: add-skillname-skill
skill_name="your-skill-name"
git checkout -b "add-${skill_name}-skill"

3. Create or Edit Skill

# Work on your skill in skills/
# Create new skill or edit existing one
# Skill should be in skills/category/skill-name/SKILL.md

4. Commit Changes

# Add and commit
git add skills/your-skill-name/
git commit -m "Add ${skill_name} skill

$(cat <<'EOF'
Brief description of what this skill does and why it's useful.

Tested with: [describe testing approach]
EOF
)"

5. Push to Your Fork

git push -u origin "add-${skill_name}-skill"

6. Create Pull Request

# Create PR to upstream using gh CLI
gh pr create \
  --repo upstream-org/upstream-repo \
  --title "Add ${skill_name} skill" \
  --body "$(cat <<'EOF'
## Summary
Brief description of the skill and what problem it solves.

## Testing
Describe how you tested this skill (pressure scenarios, baseline tests, etc.).

## Context
Any additional context about why this skill is needed and how it should be used.
EOF
)"

Complete Example

Here's a complete example of sharing a skill called "async-patterns":

# 1. Sync with upstream
cd ~/.config/superpowers/skills/
git checkout main
git pull upstream main
git push origin main

# 2. Create branch
git checkout -b "add-async-patterns-skill"

# 3. Create/edit the skill
# (Work on skills/async-patterns/SKILL.md)

# 4. Commit
git add skills/async-patterns/
git commit -m "Add async-patterns skill

Patterns for handling asynchronous operations in tests and application code.

Tested with: Multiple pressure scenarios testing agent compliance."

# 5. Push
git push -u origin "add-async-patterns-skill"

# 6. Create PR
gh pr create \
  --repo upstream-org/upstream-repo \
  --title "Add async-patterns skill" \
  --body "## Summary
Patterns for handling asynchronous operations correctly in tests and application code.

## Testing
Tested with multiple application scenarios. Agents successfully apply patterns to new code.

## Context
Addresses common async pitfalls like race conditions, improper error handling, and timing issues."

After PR is Merged

Once your PR is merged:

  1. Sync your local main branch:
cd ~/.config/superpowers/skills/
git checkout main
git pull upstream main
git push origin main
  1. Delete the feature branch:
git branch -d "add-${skill_name}-skill"
git push origin --delete "add-${skill_name}-skill"

Troubleshooting

"gh: command not found"

"Permission denied (publickey)"

"Skill already exists"

  • You're creating a modified version
  • Consider different skill name or coordinate with the skill's maintainer

PR merge conflicts

  • Rebase on latest upstream: git fetch upstream && git rebase upstream/main
  • Resolve conflicts
  • Force push: git push -f origin your-branch

Multi-Skill Contributions

Do NOT batch multiple skills in one PR.

Each skill should:

  • Have its own feature branch
  • Have its own PR
  • Be independently reviewable

Why? Individual skills can be reviewed, iterated, and merged independently.

Related Skills

  • skills/meta/writing-skills - How to create well-tested skills

FAQ

What does the sharing skills skill do?

Contribute skills back to upstream via branch and PR

How do I install sharing skills?

Run npx skills add https://github.com/obra/superpowers-skills --skill sharing-skills in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/sharing-skills/ (personal) or .claude/skills/sharing-skills/ (project).

Which AI agents can use sharing skills?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is sharing skills safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains sharing skills?

It is published by obra in obra/superpowers-skills. It has 502 recorded installs.

More from obra/superpowers-skills

View all →

getting started with skills

obra/superpowers-skills

Skills wiki intro - mandatory workflows, search tool, brainstorming triggers

949 installs

collision-zone thinking

obra/superpowers-skills

Force unrelated concepts together to discover emergent properties - "What if we treated X like Y?"

580 installs

brainstorming ideas into designs

obra/superpowers-skills

Interactive idea refinement using Socratic method to develop fully-formed designs

567 installs

test-driven development (tdd)

obra/superpowers-skills

Write the test first, watch it fail, write minimal code to pass

Testing & QA563 installs

systematic debugging

obra/superpowers-skills

Four-phase debugging framework that ensures root cause investigation before attempting fixes. Never jump to solutions.

root cause tracing

obra/superpowers-skills

Systematically trace bugs backward through call stack to find original trigger

557 installs

Popular code quality & workflow skills

View category →

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

code-review

mattpocock/skills

Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes: Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".

implement

mattpocock/skills

Implement a piece of work based on a spec or set of tickets.

wayfinder

mattpocock/skills

Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.