Sharing Skills

{
  "sections": {
    "After PR is Merged": "Once your PR is merged:\r\n\r\n1. Sync your local main branch:\r\n```bash\r\ncd ~/.config/superpowers/skills/\r\ngit checkout main\r\ngit pull upstream main\r\ngit push origin main\r\n```\r\n\r\n2. Delete the feature branch:\r\n```bash\r\ngit branch -d \"add-${skill_name}-skill\"\r\ngit push origin --delete \"add-${skill_name}-skill\"\r\n```",
    "Context": "Addresses common async pitfalls like race conditions, improper error handling, and timing issues.\"\r\n```",
    "When to Share": "**Share when:**\r\n- Skill applies broadly (not project-specific)\r\n- Pattern/technique others would benefit from\r\n- Well-tested and documented\r\n- Follows writing-skills guidelines\r\n\r\n**Keep personal when:**\r\n- Project-specific or organization-specific\r\n- Experimental or unstable\r\n- Contains sensitive information\r\n- Too narrow/niche for general use",
    "Sharing Workflow": "gh pr create \\\r\n  --repo upstream-org/upstream-repo \\\r\n  --title \"Add ${skill_name} skill\" \\\r\n  --body \"$(cat <<'EOF'",
    "Troubleshooting": "**\"gh: command not found\"**\r\n- Install GitHub CLI: https://cli.github.com/\r\n- Authenticate: `gh auth login`\r\n\r\n**\"Permission denied (publickey)\"**\r\n- Check SSH keys: `gh auth status`\r\n- Set up SSH: https://docs.github.com/en/authentication\r\n\r\n**\"Skill already exists\"**\r\n- You're creating a modified version\r\n- Consider different skill name or coordinate with the skill's maintainer\r\n\r\n**PR merge conflicts**\r\n- Rebase on latest upstream: `git fetch upstream && git rebase upstream/main`\r\n- Resolve conflicts\r\n- Force push: `git push -f origin your-branch`",
    "Prerequisites": "- `gh` CLI installed and authenticated\r\n- Working directory is `~/.config/superpowers/skills/` (your local clone)\r\n- **REQUIRED:** Skill has been tested using writing-skills TDD process",
    "Overview": "Contribute skills from your local branch back to the upstream repository.\r\n\r\n**Workflow:** Branch → Edit/Create skill → Commit → Push → PR",
    "Summary": "Brief description of the skill and what problem it solves.",
    "Related Skills": "- **writing-skills** - REQUIRED: How to create well-tested skills before sharing",
    "Multi-Skill Contributions": "**Do NOT batch multiple skills in one PR.**\r\n\r\nEach skill should:\r\n- Have its own feature branch\r\n- Have its own PR\r\n- Be independently reviewable\r\n\r\n**Why?** Individual skills can be reviewed, iterated, and merged independently.",
    "Testing": "Tested with multiple application scenarios. Agents successfully apply patterns to new code.",
    "Complete Example": "gh pr create \\\r\n  --repo upstream-org/upstream-repo \\\r\n  --title \"Add async-patterns skill\" \\\r\n  --body \"## Summary\r\nPatterns for handling asynchronous operations correctly in tests and application code."
  },
  "content": "### 1. Ensure You're on Main and Synced\r\n\r\n```bash\r\ncd ~/.config/superpowers/skills/\r\ngit checkout main\r\ngit pull upstream main\r\ngit push origin main  # Push to your fork\r\n```\r\n\r\n### 2. Create Feature Branch\r\n\r\n```bash\r\nskill_name=\"your-skill-name\"\r\ngit checkout -b \"add-${skill_name}-skill\"\r\n```\r\n\r\n### 3. Create or Edit Skill\r\n\r\n```bash\r\n```\r\n\r\n### 4. Commit Changes\r\n\r\n```bash\r\ngit add skills/your-skill-name/\r\ngit commit -m \"Add ${skill_name} skill\r\n\r\n$(cat <<'EOF'\r\nBrief description of what this skill does and why it's useful.\r\n\r\nTested with: [describe testing approach]\r\nEOF\r\n)\"\r\n```\r\n\r\n### 5. Push to Your Fork\r\n\r\n```bash\r\ngit push -u origin \"add-${skill_name}-skill\"\r\n```\r\n\r\n### 6. Create Pull Request\r\n\r\n```bash\r\n\r\nHere's a complete example of sharing a skill called \"async-patterns\":\r\n\r\n```bash\r\ncd ~/.config/superpowers/skills/\r\ngit checkout main\r\ngit pull upstream main\r\ngit push origin main\r\n\r\ngit checkout -b \"add-async-patterns-skill\"\r\n\r\n\r\ngit add skills/async-patterns/\r\ngit commit -m \"Add async-patterns skill\r\n\r\nPatterns for handling asynchronous operations in tests and application code.\r\n\r\nTested with: Multiple pressure scenarios testing agent compliance.\"\r\n\r\ngit push -u origin \"add-async-patterns-skill\"",
  "id": "sharing-skills_obra",
  "name": "sharing-skills",
  "description": "Use when you've developed a broadly useful skill and want to contribute it upstream via pull request - guides process of branching, committing, pushing, and creating PR to contribute skills back to upstream repository"
}

---
name: sharing-skills
description: Use when you've developed a broadly useful skill and want to contribute it upstream via pull request - guides process of branching, committing, pushing, and creating PR to contribute skills back to upstream repository
---

# 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 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)
- **REQUIRED:** Skill has been tested using writing-skills TDD process

## Sharing Workflow

### 1. Ensure You're on Main and Synced

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

### 2. Create Feature Branch

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

### 3. Create or Edit Skill

```bash
# 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

```bash
# 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

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

### 6. Create Pull Request

```bash
# 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":

```bash
# 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:
```bash
cd ~/.config/superpowers/skills/
git checkout main
git pull upstream main
git push origin main
```

2. Delete the feature branch:
```bash
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

- **writing-skills** - REQUIRED: How to create well-tested skills before sharing