Move superpowers plugin into plugins/superpowers-bootstrap subdirectory

This restructures the repo to support multiple plugins by moving the current plugin into a subdirectory. The plugin continues to be published as "superpowers" in the marketplace.
2026-04-22 01:19:04 +08:00 · 2025-10-15 22:27:45 -07:00
parent 02429d7e26
commit 809956f3bf
11 changed files with 0 additions and 0 deletions
--- a/plugins/superpowers-bootstrap/.claude-plugin/plugin.json
+++ b/plugins/superpowers-bootstrap/.claude-plugin/plugin.json
@@ -0,0 +1,13 @@
+{
+  "name": "superpowers",
+  "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
+  "version": "2.0.4",
+  "author": {
+    "name": "Jesse Vincent",
+    "email": "jesse@fsck.com"
+  },
+  "homepage": "https://github.com/obra/superpowers",
+  "repository": "https://github.com/obra/superpowers",
+  "license": "MIT",
+  "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"]
+}
--- a/plugins/superpowers-bootstrap/LICENSE
+++ b/plugins/superpowers-bootstrap/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/plugins/superpowers-bootstrap/README.md
+++ b/plugins/superpowers-bootstrap/README.md
@@ -0,0 +1,171 @@
+# Superpowers
+
+Give Claude Code superpowers with a comprehensive skills library of proven techniques, patterns, and tools.
+
+## Architecture
+
+The superpowers plugin is a minimal shim that:
+- Clones/updates the [superpowers-skills](https://github.com/obra/superpowers-skills) repository to `~/.config/superpowers/skills/`
+- Registers hooks that load skills from the local repository
+- Offers users the option to fork the skills repo for contributions
+
+All skills, scripts, and documentation live in the separate [superpowers-skills](https://github.com/obra/superpowers-skills) repository. Edit skills locally, commit changes, and contribute back via pull requests.
+
+**Skills Repository:** https://github.com/obra/superpowers-skills
+
+## What You Get
+
+- **Testing Skills** - TDD, async testing, anti-patterns
+- **Debugging Skills** - Systematic debugging, root cause tracing, verification
+- **Collaboration Skills** - Brainstorming, planning, code review, parallel agents
+- **Meta Skills** - Creating, testing, and contributing skills
+
+Plus:
+- **Slash Commands** - `/brainstorm`, `/write-plan`, `/execute-plan`
+- **Skills Search** - Grep-powered discovery of relevant skills
+- **Gap Tracking** - Failed searches logged for skill creation
+
+## Learn More
+
+Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/10/09/superpowers/)
+
+## Installation
+
+### Via Plugin Marketplace (Recommended)
+
+```bash
+# In Claude Code
+/plugin marketplace add obra/superpowers-marketplace
+/plugin install superpowers@superpowers-marketplace
+```
+
+The plugin automatically handles skills repository setup on first run.
+
+### Verify Installation
+
+```bash
+# Check that commands appear
+/help
+
+# Should see:
+# /brainstorm - Interactive design refinement
+# /write-plan - Create implementation plan
+# /execute-plan - Execute plan in batches
+```
+
+## Updating Skills
+
+The plugin fetches and fast-forwards your local skills repository on each session start. If your local branch has diverged, Claude notifies you to use the pulling-updates-from-skills-repository skill.
+
+## Contributing Skills
+
+If you forked the skills repository during setup, you can contribute improvements:
+
+1. Edit skills in `~/.config/superpowers/skills/`
+2. Commit your changes
+3. Push to your fork
+4. Open a PR to `obra/superpowers-skills`
+
+## Quick Start
+
+### Finding Skills
+
+Find skills before starting any task:
+
+```bash
+${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills              # All skills with descriptions
+${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills test         # Filter by pattern
+${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills 'TDD|debug'  # Regex pattern
+```
+
+### Using Slash Commands
+
+**Brainstorm a design:**
+```
+/brainstorm
+```
+
+**Create an implementation plan:**
+```
+/write-plan
+```
+
+**Execute the plan:**
+```
+/execute-plan
+```
+
+## What's Inside
+
+### Skills Library
+
+**Testing** (`skills/testing/`)
+- test-driven-development - RED-GREEN-REFACTOR cycle
+- condition-based-waiting - Async test patterns
+- testing-anti-patterns - Common pitfalls to avoid
+
+**Debugging** (`skills/debugging/`)
+- systematic-debugging - 4-phase root cause process
+- root-cause-tracing - Find the real problem
+- verification-before-completion - Ensure it's actually fixed
+- defense-in-depth - Multiple validation layers
+
+**Collaboration** (`skills/collaboration/`)
+- brainstorming - Socratic design refinement
+- writing-plans - Detailed implementation plans
+- executing-plans - Batch execution with checkpoints
+- dispatching-parallel-agents - Concurrent subagent workflows
+- remembering-conversations - Search past work
+- using-git-worktrees - Parallel development branches
+- requesting-code-review - Pre-review checklist
+- receiving-code-review - Responding to feedback
+
+**Meta** (`skills/meta/`)
+- writing-skills - TDD for documentation, create new skills
+- sharing-skills - Contribute skills back via branch and PR
+- testing-skills-with-subagents - Validate skill quality
+- pulling-updates-from-skills-repository - Sync with upstream
+- gardening-skills-wiki - Maintain and improve skills
+
+### Commands
+
+- **brainstorm.md** - Interactive design refinement using Socratic method
+- **write-plan.md** - Create detailed implementation plans
+- **execute-plan.md** - Execute plans in batches with review checkpoints
+
+### Tools
+
+- **find-skills** - Unified skill discovery with descriptions
+- **skill-run** - Generic runner for any skill script
+- **search-conversations** - Semantic search of past Claude sessions (in remembering-conversations skill)
+
+**Using tools:**
+```bash
+${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills              # Show all skills
+${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills pattern      # Search skills
+${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/skill-run <path> [args]  # Run any skill script
+```
+
+## How It Works
+
+1. **SessionStart Hook** - Clone/update skills repo, inject skills context
+2. **Skills Discovery** - `find-skills` shows all available skills with descriptions
+3. **Mandatory Workflow** - Skills become required when they exist for your task
+4. **Gap Tracking** - Failed searches logged for skill development
+
+## Philosophy
+
+- **Test-Driven Development** - Write tests first, always
+- **Systematic over ad-hoc** - Process over guessing
+- **Complexity reduction** - Simplicity as primary goal
+- **Evidence over claims** - Verify before declaring success
+- **Domain over implementation** - Work at problem level, not solution level
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Support
+
+- **Issues**: https://github.com/obra/superpowers/issues
+- **Marketplace**: https://github.com/obra/superpowers-marketplace
--- a/plugins/superpowers-bootstrap/RELEASE-NOTES.md
+++ b/plugins/superpowers-bootstrap/RELEASE-NOTES.md
@@ -0,0 +1,249 @@
+# Superpowers Release Notes
+
+## v2.0.2 (2025-10-12)
+
+### Bug Fixes
+
+- **Fixed false warning when local skills repo is ahead of upstream** - The initialization script was incorrectly warning "New skills available from upstream" when the local repository had commits ahead of upstream. The logic now correctly distinguishes between three git states: local behind (should update), local ahead (no warning), and diverged (should warn).
+
+## v2.0.1 (2025-10-12)
+
+### Bug Fixes
+
+- **Fixed session-start hook execution in plugin context** (#8, PR #9) - The hook was failing silently with "Plugin hook error" preventing skills context from loading. Fixed by:
+  - Using `${BASH_SOURCE[0]:-$0}` fallback when BASH_SOURCE is unbound in Claude Code's execution context
+  - Adding `|| true` to handle empty grep results gracefully when filtering status flags
+
+---
+
+# Superpowers v2.0.0 Release Notes
+
+## Overview
+
+Superpowers v2.0 makes skills more accessible, maintainable, and community-driven through a major architectural shift.
+
+The headline change is **skills repository separation**: all skills, scripts, and documentation have moved from the plugin into a dedicated repository ([obra/superpowers-skills](https://github.com/obra/superpowers-skills)). This transforms superpowers from a monolithic plugin into a lightweight shim that manages a local clone of the skills repository. Skills auto-update on session start. Users fork and contribute improvements via standard git workflows. The skills library versions independently from the plugin.
+
+Beyond infrastructure, this release adds nine new skills focused on problem-solving, research, and architecture. We rewrote the core **using-skills** documentation with imperative tone and clearer structure, making it easier for Claude to understand when and how to use skills. **find-skills** now outputs paths you can paste directly into the Read tool, eliminating friction in the skills discovery workflow.
+
+Users experience seamless operation: the plugin handles cloning, forking, and updating automatically. Contributors find the new architecture makes improving and sharing skills trivial. This release lays the foundation for skills to evolve rapidly as a community resource.
+
+## Breaking Changes
+
+### Skills Repository Separation
+
+**The biggest change:** Skills no longer live in the plugin. They've been moved to a separate repository at [obra/superpowers-skills](https://github.com/obra/superpowers-skills).
+
+**What this means for you:**
+
+- **First install:** Plugin automatically clones skills to `~/.config/superpowers/skills/`
+- **Forking:** During setup, you'll be offered the option to fork the skills repo (if `gh` is installed)
+- **Updates:** Skills auto-update on session start (fast-forward when possible)
+- **Contributing:** Work on branches, commit locally, submit PRs to upstream
+- **No more shadowing:** Old two-tier system (personal/core) replaced with single-repo branch workflow
+
+**Migration:**
+
+If you have an existing installation:
+1. Your old `~/.config/superpowers/.git` will be backed up to `~/.config/superpowers/.git.bak`
+2. Old skills will be backed up to `~/.config/superpowers/skills.bak`
+3. Fresh clone of obra/superpowers-skills will be created at `~/.config/superpowers/skills/`
+
+### Removed Features
+
+- **Personal superpowers overlay system** - Replaced with git branch workflow
+- **setup-personal-superpowers hook** - Replaced by initialize-skills.sh
+
+## New Features
+
+### Skills Repository Infrastructure
+
+**Automatic Clone & Setup** (`lib/initialize-skills.sh`)
+- Clones obra/superpowers-skills on first run
+- Offers fork creation if GitHub CLI is installed
+- Sets up upstream/origin remotes correctly
+- Handles migration from old installation
+
+**Auto-Update**
+- Fetches from tracking remote on every session start
+- Auto-merges with fast-forward when possible
+- Notifies when manual sync needed (branch diverged)
+- Uses pulling-updates-from-skills-repository skill for manual sync
+
+### New Skills
+
+**Problem-Solving Skills** (`skills/problem-solving/`)
+- **collision-zone-thinking** - Force unrelated concepts together for emergent insights
+- **inversion-exercise** - Flip assumptions to reveal hidden constraints
+- **meta-pattern-recognition** - Spot universal principles across domains
+- **scale-game** - Test at extremes to expose fundamental truths
+- **simplification-cascades** - Find insights that eliminate multiple components
+- **when-stuck** - Dispatch to right problem-solving technique
+
+**Research Skills** (`skills/research/`)
+- **tracing-knowledge-lineages** - Understand how ideas evolved over time
+
+**Architecture Skills** (`skills/architecture/`)
+- **preserving-productive-tensions** - Keep multiple valid approaches instead of forcing premature resolution
+
+### Skills Improvements
+
+**using-skills (formerly getting-started)**
+- Renamed from getting-started to using-skills
+- Complete rewrite with imperative tone (v4.0.0)
+- Front-loaded critical rules
+- Added "Why" explanations for all workflows
+- Always includes /SKILL.md suffix in references
+- Clearer distinction between rigid rules and flexible patterns
+
+**writing-skills**
+- Cross-referencing guidance moved from using-skills
+- Added token efficiency section (word count targets)
+- Improved CSO (Claude Search Optimization) guidance
+
+**sharing-skills**
+- Updated for new branch-and-PR workflow (v2.0.0)
+- Removed personal/core split references
+
+**pulling-updates-from-skills-repository** (new)
+- Complete workflow for syncing with upstream
+- Replaces old "updating-skills" skill
+
+### Tools Improvements
+
+**find-skills**
+- Now outputs full paths with /SKILL.md suffix
+- Makes paths directly usable with Read tool
+- Updated help text
+
+**skill-run**
+- Moved from scripts/ to skills/using-skills/
+- Improved documentation
+
+### Plugin Infrastructure
+
+**Session Start Hook**
+- Now loads from skills repository location
+- Shows full skills list at session start
+- Prints skills location info
+- Shows update status (updated successfully / behind upstream)
+- Moved "skills behind" warning to end of output
+
+**Environment Variables**
+- `SUPERPOWERS_SKILLS_ROOT` set to `~/.config/superpowers/skills`
+- Used consistently throughout all paths
+
+## Bug Fixes
+
+- Fixed duplicate upstream remote addition when forking
+- Fixed find-skills double "skills/" prefix in output
+- Removed obsolete setup-personal-superpowers call from session-start
+- Fixed path references throughout hooks and commands
+
+## Documentation
+
+### README
+- Updated for new skills repository architecture
+- Prominent link to superpowers-skills repo
+- Updated auto-update description
+- Fixed skill names and references
+- Updated Meta skills list
+
+### Testing Documentation
+- Added comprehensive testing checklist (`docs/TESTING-CHECKLIST.md`)
+- Created local marketplace config for testing
+- Documented manual testing scenarios
+
+## Technical Details
+
+### File Changes
+
+**Added:**
+- `lib/initialize-skills.sh` - Skills repo initialization and auto-update
+- `docs/TESTING-CHECKLIST.md` - Manual testing scenarios
+- `.claude-plugin/marketplace.json` - Local testing config
+
+**Removed:**
+- `skills/` directory (82 files) - Now in obra/superpowers-skills
+- `scripts/` directory - Now in obra/superpowers-skills/skills/using-skills/
+- `hooks/setup-personal-superpowers.sh` - Obsolete
+
+**Modified:**
+- `hooks/session-start.sh` - Use skills from ~/.config/superpowers/skills
+- `commands/brainstorm.md` - Updated paths to SUPERPOWERS_SKILLS_ROOT
+- `commands/write-plan.md` - Updated paths to SUPERPOWERS_SKILLS_ROOT
+- `commands/execute-plan.md` - Updated paths to SUPERPOWERS_SKILLS_ROOT
+- `README.md` - Complete rewrite for new architecture
+
+### Commit History
+
+This release includes:
+- 20+ commits for skills repository separation
+- PR #1: Amplifier-inspired problem-solving and research skills
+- PR #2: Personal superpowers overlay system (later replaced)
+- Multiple skill refinements and documentation improvements
+
+## Upgrade Instructions
+
+### Fresh Install
+
+```bash
+# In Claude Code
+/plugin marketplace add obra/superpowers-marketplace
+/plugin install superpowers@superpowers-marketplace
+```
+
+The plugin handles everything automatically.
+
+### Upgrading from v1.x
+
+1. **Backup your personal skills** (if you have any):
+   ```bash
+   cp -r ~/.config/superpowers/skills ~/superpowers-skills-backup
+   ```
+
+2. **Update the plugin:**
+   ```bash
+   /plugin update superpowers
+   ```
+
+3. **On next session start:**
+   - Old installation will be backed up automatically
+   - Fresh skills repo will be cloned
+   - If you have GitHub CLI, you'll be offered the option to fork
+
+4. **Migrate personal skills** (if you had any):
+   - Create a branch in your local skills repo
+   - Copy your personal skills from backup
+   - Commit and push to your fork
+   - Consider contributing back via PR
+
+## What's Next
+
+### For Users
+
+- Explore the new problem-solving skills
+- Try the branch-based workflow for skill improvements
+- Contribute skills back to the community
+
+### For Contributors
+
+- Skills repository is now at https://github.com/obra/superpowers-skills
+- Fork → Branch → PR workflow
+- See skills/meta/writing-skills/SKILL.md for TDD approach to documentation
+
+## Known Issues
+
+None at this time.
+
+## Credits
+
+- Problem-solving skills inspired by Amplifier patterns
+- Community contributions and feedback
+- Extensive testing and iteration on skill effectiveness
+
+---
+
+**Full Changelog:** https://github.com/obra/superpowers/compare/dd013f6...main
+**Skills Repository:** https://github.com/obra/superpowers-skills
+**Issues:** https://github.com/obra/superpowers/issues
--- a/plugins/superpowers-bootstrap/commands/README.md
+++ b/plugins/superpowers-bootstrap/commands/README.md
@@ -0,0 +1,36 @@
+# Claude Commands
+
+Slash commands for Claude that reference skills.
+
+## Available Commands
+
+- `/brainstorm` - Interactive idea refinement using Socratic method (→ `@skills/collaboration/brainstorming/SKILL.md`)
+- `/write-plan` - Create detailed implementation plan (→ `@skills/collaboration/writing-plans/SKILL.md`)
+- `/execute-plan` - Execute plan in batches with review (→ `@skills/collaboration/executing-plans/SKILL.md`)
+
+## Format
+
+Each command is a simple markdown file containing a single `@` reference to a skill:
+
+```markdown
+@skills/collaboration/brainstorming/SKILL.md
+```
+
+When you run the command (e.g., `/brainstorm`), Claude loads and follows that skill.
+
+## Creating Custom Commands
+
+To add your own commands:
+
+1. Create `your-command.md` in this directory
+2. Add a single line referencing a skill:
+   ```markdown
+   @skills/your-category/your-skill/SKILL.md
+   ```
+3. The command `/your-command` is now available
+
+## Installation
+
+These commands are automatically symlinked to `~/.claude/commands/` by the clank installer.
+
+See `@skills/meta/installing-skills/SKILL.md` for installation details.
--- a/plugins/superpowers-bootstrap/commands/brainstorm.md
+++ b/plugins/superpowers-bootstrap/commands/brainstorm.md
@@ -0,0 +1,5 @@
+---
+description: Interactive design refinement using Socratic method
+---
+
+Read and follow: ${SUPERPOWERS_SKILLS_ROOT}/skills/collaboration/brainstorming/SKILL.md
--- a/plugins/superpowers-bootstrap/commands/execute-plan.md
+++ b/plugins/superpowers-bootstrap/commands/execute-plan.md
@@ -0,0 +1,5 @@
+---
+description: Execute plan in batches with review checkpoints
+---
+
+Read and follow: ${SUPERPOWERS_SKILLS_ROOT}/skills/collaboration/executing-plans/SKILL.md
--- a/plugins/superpowers-bootstrap/commands/write-plan.md
+++ b/plugins/superpowers-bootstrap/commands/write-plan.md
@@ -0,0 +1,5 @@
+---
+description: Create detailed implementation plan with bite-sized tasks
+---
+
+Read and follow: ${SUPERPOWERS_SKILLS_ROOT}/skills/collaboration/writing-plans/SKILL.md
--- a/plugins/superpowers-bootstrap/hooks/hooks.json
+++ b/plugins/superpowers-bootstrap/hooks/hooks.json
@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
--- a/plugins/superpowers-bootstrap/hooks/session-start.sh
+++ b/plugins/superpowers-bootstrap/hooks/session-start.sh
@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# SessionStart hook for superpowers plugin
+
+set -euo pipefail
+
+# Set SUPERPOWERS_SKILLS_ROOT environment variable
+export SUPERPOWERS_SKILLS_ROOT="${HOME}/.config/superpowers/skills"
+
+# Run skills initialization script (handles clone/fetch/auto-update)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+init_output=$("${PLUGIN_ROOT}/lib/initialize-skills.sh" 2>&1 || echo "")
+
+# Extract status flags
+skills_updated=$(echo "$init_output" | grep "SKILLS_UPDATED=true" || echo "")
+skills_behind=$(echo "$init_output" | grep "SKILLS_BEHIND=true" || echo "")
+# Remove status flags from display output
+init_output=$(echo "$init_output" | grep -v "SKILLS_UPDATED=true" | grep -v "SKILLS_BEHIND=true" || true)
+
+# Run find-skills to show all available skills
+find_skills_output=$("${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills" 2>&1 || echo "Error running find-skills")
+
+# Read using-skills content (renamed from getting-started)
+using_skills_content=$(cat "${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/SKILL.md" 2>&1 || echo "Error reading using-skills")
+
+# Escape outputs for JSON
+init_escaped=$(echo "$init_output" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
+find_skills_escaped=$(echo "$find_skills_output" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
+using_skills_escaped=$(echo "$using_skills_content" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
+
+# Build initialization output message if present
+init_message=""
+if [ -n "$init_escaped" ]; then
+    init_message="${init_escaped}\n\n"
+fi
+
+# Build status messages that go at the end
+status_message=""
+if [ -n "$skills_behind" ]; then
+    status_message="\n\n⚠️ New skills available from upstream. Ask me to use the pulling-updates-from-skills-repository skill."
+fi
+
+# Output context injection as JSON
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n${init_message}**The content below is from skills/using-skills/SKILL.md - your introduction to using skills:**\n\n${using_skills_escaped}\n\n**Tool paths (use these when you need to search for or run skills):**\n- find-skills: ${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills\n- skill-run: ${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/skill-run\n\n**Skills live in:** ${SUPERPOWERS_SKILLS_ROOT}/skills/ (you work on your own branch and can edit any skill)\n\n**Available skills (output of find-skills):**\n\n${find_skills_escaped}${status_message}\n</EXTREMELY_IMPORTANT>"
+  }
+}
+EOF
+
+exit 0
--- a/plugins/superpowers-bootstrap/lib/initialize-skills.sh
+++ b/plugins/superpowers-bootstrap/lib/initialize-skills.sh
@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SKILLS_DIR="${HOME}/.config/superpowers/skills"
+SKILLS_REPO="https://github.com/obra/superpowers-skills.git"
+
+# Check if skills directory exists and is a valid git repo
+if [ -d "$SKILLS_DIR/.git" ]; then
+    cd "$SKILLS_DIR"
+
+    # Get the remote name for the current tracking branch
+    TRACKING_REMOTE=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null | cut -d'/' -f1 || echo "")
+
+    # Fetch from tracking remote if set, otherwise try upstream then origin
+    if [ -n "$TRACKING_REMOTE" ]; then
+        git fetch "$TRACKING_REMOTE" 2>/dev/null || true
+    else
+        git fetch upstream 2>/dev/null || git fetch origin 2>/dev/null || true
+    fi
+
+    # Check if we can fast-forward
+    LOCAL=$(git rev-parse @ 2>/dev/null || echo "")
+    REMOTE=$(git rev-parse @{u} 2>/dev/null || echo "")
+    BASE=$(git merge-base @ @{u} 2>/dev/null || echo "")
+
+    # Try to fast-forward merge first
+    if [ -n "$LOCAL" ] && [ -n "$REMOTE" ] && [ "$LOCAL" != "$REMOTE" ]; then
+        # Check if we can fast-forward (local is ancestor of remote)
+        if [ "$LOCAL" = "$BASE" ]; then
+            # Fast-forward merge is possible - local is behind
+            echo "Updating skills to latest version..."
+            if git merge --ff-only @{u} 2>&1; then
+                echo "✓ Skills updated successfully"
+                echo "SKILLS_UPDATED=true"
+            else
+                echo "Failed to update skills"
+            fi
+        elif [ "$REMOTE" != "$BASE" ]; then
+            # Remote has changes (local is behind or diverged)
+            echo "SKILLS_BEHIND=true"
+        fi
+        # If REMOTE = BASE, local is ahead - no action needed
+    fi
+
+    exit 0
+fi
+
+# Skills directory doesn't exist or isn't a git repo - initialize it
+echo "Initializing skills repository..."
+
+# Handle migration from old installation
+if [ -d "${HOME}/.config/superpowers/.git" ]; then
+    echo "Found existing installation. Backing up..."
+    mv "${HOME}/.config/superpowers/.git" "${HOME}/.config/superpowers/.git.bak"
+
+    if [ -d "${HOME}/.config/superpowers/skills" ]; then
+        mv "${HOME}/.config/superpowers/skills" "${HOME}/.config/superpowers/skills.bak"
+        echo "Your old skills are in ~/.config/superpowers/skills.bak"
+    fi
+fi
+
+# Clone the skills repository
+mkdir -p "${HOME}/.config/superpowers"
+git clone "$SKILLS_REPO" "$SKILLS_DIR"
+
+cd "$SKILLS_DIR"
+
+# Offer to fork if gh is installed
+if command -v gh &> /dev/null; then
+    echo ""
+    echo "GitHub CLI detected. Would you like to fork superpowers-skills?"
+    echo "Forking allows you to share skill improvements with the community."
+    echo ""
+    read -p "Fork superpowers-skills? (y/N): " -n 1 -r
+    echo
+
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        gh repo fork obra/superpowers-skills --remote=true
+        echo "Forked! You can now contribute skills back to the community."
+    else
+        git remote add upstream "$SKILLS_REPO"
+    fi
+else
+    # No gh, just set up upstream remote
+    git remote add upstream "$SKILLS_REPO"
+fi
+
+echo "Skills repository initialized at $SKILLS_DIR"