
- 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- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads sharing skills automatically when relevant.
- 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
ghCLI 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:
- Sync your local main branch:
cd ~/.config/superpowers/skills/
git checkout main
git pull upstream main
git push origin main
- Delete the feature branch:
git branch -d "add-${skill_name}-skill"
git push origin --delete "add-${skill_name}-skill"
Troubleshooting
"gh: command not found"
- Install GitHub CLI: https://cli.github.com/
- Authenticate:
gh auth login
"Permission denied (publickey)"
- Check SSH keys:
gh auth status - Set up SSH: https://docs.github.com/en/authentication
"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
getting started with skills
obra/superpowers-skills
Skills wiki intro - mandatory workflows, search tool, brainstorming triggers
collision-zone thinking
obra/superpowers-skills
Force unrelated concepts together to discover emergent properties - "What if we treated X like Y?"
brainstorming ideas into designs
obra/superpowers-skills
Interactive idea refinement using Socratic method to develop fully-formed designs
test-driven development (tdd)
obra/superpowers-skills
Write the test first, watch it fail, write minimal code to pass
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
Popular code quality & workflow skills
improve-codebase-architecture
mattpocock/skills
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.