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

bash
1cd ~/.config/superpowers/skills/
2git checkout main
3git pull upstream main
4git push origin main  # Push to your fork

2. Create Feature Branch

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

3. Create or Edit Skill

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

4. Commit Changes

bash
1# Add and commit
2git add skills/your-skill-name/
3git commit -m "Add ${skill_name} skill
4
5$(cat <<'EOF'
6Brief description of what this skill does and why it's useful.
7
8Tested with: [describe testing approach]
9EOF
10)"

5. Push to Your Fork

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

6. Create Pull Request

bash
1# Create PR to upstream using gh CLI
2gh pr create \
3  --repo upstream-org/upstream-repo \
4  --title "Add ${skill_name} skill" \
5  --body "$(cat <<'EOF'
6## Summary
7Brief description of the skill and what problem it solves.
8
9## Testing
10Describe how you tested this skill (pressure scenarios, baseline tests, etc.).
11
12## Context
13Any additional context about why this skill is needed and how it should be used.
14EOF
15)"

Complete Example

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

bash
1# 1. Sync with upstream
2cd ~/.config/superpowers/skills/
3git checkout main
4git pull upstream main
5git push origin main
6
7# 2. Create branch
8git checkout -b "add-async-patterns-skill"
9
10# 3. Create/edit the skill
11# (Work on skills/async-patterns/SKILL.md)
12
13# 4. Commit
14git add skills/async-patterns/
15git commit -m "Add async-patterns skill
16
17Patterns for handling asynchronous operations in tests and application code.
18
19Tested with: Multiple pressure scenarios testing agent compliance."
20
21# 5. Push
22git push -u origin "add-async-patterns-skill"
23
24# 6. Create PR
25gh pr create \
26  --repo upstream-org/upstream-repo \
27  --title "Add async-patterns skill" \
28  --body "## Summary
29Patterns for handling asynchronous operations correctly in tests and application code.
30
31## Testing
32Tested with multiple application scenarios. Agents successfully apply patterns to new code.
33
34## Context
35Addresses 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:

bash
1cd ~/.config/superpowers/skills/
2git checkout main
3git pull upstream main
4git push origin main

2. Delete the feature branch:

bash
1git branch -d "add-${skill_name}-skill"
2git 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