Add personal superpowers overlay system

Enables users to write and manage their own skills alongside core skills.

## Key Features:
- Auto-setup on first session: Creates ~/.config/superpowers/ git repo
- Two-tier skills: Personal skills shadow core skills when paths match
- Environment variable support: PERSONAL_SUPERPOWERS_DIR, XDG_CONFIG_HOME
- GitHub integration: Optional public repo creation for sharing skills
- CLI-agnostic: Works across Claude Code, Codex CLI, Gemini CLI (future)

## Changes:
- Added hooks/setup-personal-superpowers.sh - Auto-initializes personal repo
- Updated hooks/session-start.sh - Runs setup, offers GitHub repo creation
- Updated list-skills, skills-search - Search both personal and core skills
- Renamed skills/meta/creating-skills → writing-skills
- Added skills/meta/setting-up-personal-superpowers - Setup documentation
- Added skills/meta/sharing-skills - Contribution workflow
- Removed skills/meta/installing-skills - Old ~/.clank system
- Removed all INDEX.md files - Replaced by list-skills tool
- Updated README.md, getting-started - Document personal skills workflow

## Architecture:
~/.config/superpowers/skills/  # Personal (user-created, git-tracked)
${CLAUDE_PLUGIN_ROOT}/skills/  # Core (read-only, from plugin)

Search order: Personal first, core second (first match wins)

README.md

@@ -28,11 +28,12 @@ Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/
 /plugin install superpowers@superpowers-marketplace
 ```
 
-That's it! The plugin will:
-- Inject skills library into your session context
-- Make skills searchable via `${CLAUDE_PLUGIN_ROOT}/skills/getting-started/skills-search`
-- Add `/brainstorm`, `/write-plan`, and `/execute-plan` commands
-- Create `~/.superpowers/` for local data
+That's it! On first session, the plugin automatically:
+- Sets up `~/.config/superpowers/` as your personal skills repository
+- Initializes git repo for version control
+- Makes core skills searchable alongside your personal skills
+- Adds `/brainstorm`, `/write-plan`, and `/execute-plan` commands
+- Offers to create public GitHub repo for sharing your skills
 
 ### Verify Installation
 
@@ -48,14 +49,25 @@ That's it! The plugin will:
 
 ## Quick Start
 
+### Your Personal Skills
+
+Write your own skills to `~/.config/superpowers/skills/`:
+- All personal skills automatically discovered by search tools
+- Personal skills shadow core skills when names match
+- Version controlled with git
+- Optional: Share on GitHub and contribute back to core
+
+See `skills/meta/writing-skills` for how to create new skills.
+See `skills/meta/sharing-skills` for how to contribute to core.
+
 ### Finding Skills
 
-Search for relevant skills before starting any task:
+Search both personal and core skills before starting any task:
 
 ```bash
+${CLAUDE_PLUGIN_ROOT}/skills/getting-started/list-skills  # See all available
 ${CLAUDE_PLUGIN_ROOT}/skills/getting-started/skills-search 'test.*driven|TDD'
 ${CLAUDE_PLUGIN_ROOT}/skills/getting-started/skills-search 'debug.*systematic'
-${CLAUDE_PLUGIN_ROOT}/skills/getting-started/skills-search 'refactor'
 ```
 
 ### Using Slash Commands
@@ -101,7 +113,9 @@ ${CLAUDE_PLUGIN_ROOT}/skills/getting-started/skills-search 'refactor'
 - receiving-code-review - Responding to feedback
 
 **Meta** (`skills/meta/`)
-- creating-skills - Document new techniques
+- setting-up-personal-superpowers - Personal skills repository setup
+- writing-skills - TDD for documentation, create new skills
+- sharing-skills - Contribute skills back to core
 - testing-skills-with-subagents - Validate skill quality
 - gardening-skills-wiki - Maintain and improve skills
 
@@ -118,10 +132,12 @@ ${CLAUDE_PLUGIN_ROOT}/skills/getting-started/skills-search 'refactor'
 
 ## How It Works
 
-1. **SessionStart Hook** - Injects skills library context at session start
-2. **Skills Discovery** - `skills-search` finds relevant skills using grep patterns
-3. **Mandatory Workflow** - Skills become required when they exist for your task
-4. **Gap Tracking** - Failed searches logged to `~/.superpowers/search-log.jsonl`
+1. **SessionStart Hook** - Auto-setup personal skills repo, inject core skills context
+2. **Two-Tier Skills** - Personal skills (`~/.config/superpowers/skills/`) + Core skills (plugin)
+3. **Skills Discovery** - `list-skills` and `skills-search` find skills from both locations
+4. **Shadowing** - Personal skills override core skills when paths match
+5. **Mandatory Workflow** - Skills become required when they exist for your task
+6. **Gap Tracking** - Failed searches logged to `~/.config/superpowers/search-log.jsonl`
 
 ## Philosophy
 
@@ -131,21 +147,49 @@ ${CLAUDE_PLUGIN_ROOT}/skills/getting-started/skills-search 'refactor'
 - **Evidence over claims** - Verify before declaring success
 - **Domain over implementation** - Work at problem level, not solution level
 
-## Data Directory
+## Personal Superpowers Directory
+
+The plugin auto-creates your personal superpowers directory on first session.
+
+**Default location:** `~/.config/superpowers/`
 
-The plugin creates `~/.superpowers/` for local data:
+**Customize via environment variables:**
+```bash
+# Option 1: Set exact location
+export PERSONAL_SUPERPOWERS_DIR="$HOME/my-superpowers"
+
+# Option 2: Use XDG standard
+export XDG_CONFIG_HOME="$HOME/.local/config"  # Uses $HOME/.local/config/superpowers
+```
 
+**Structure:**
 ```
-~/.superpowers/
-├── search-log.jsonl          # Failed skill searches
-└── conversation-index/       # Indexed past conversations (if enabled)
+~/.config/superpowers/        # (or your custom location)
+├── .git/                     # Git repository
+├── .gitignore                # Ignores logs and indexes
+├── README.md                 # About your personal superpowers
+├── skills/                   # Your personal skills
+│   └── your-skill/
+│       └── SKILL.md
+├── search-log.jsonl          # Failed skill searches (not tracked)
+└── conversation-index/       # Indexed conversations (not tracked)
 ```
 
+**Why git?** Track your skills evolution, share with others, contribute back to core.
+
 ## Contributing
 
-Want to add a skill? See `skills/meta/creating-skills/SKILL.md`
+**Write personal skills:**
+1. Create in `~/.config/superpowers/skills/your-skill/`
+2. Follow TDD process in `skills/meta/writing-skills`
+3. Commit to your personal repo
+
+**Share with everyone:**
+1. Follow workflow in `skills/meta/sharing-skills`
+2. Fork → Branch → Copy → PR to core
+3. Keep personal version or delete after merge
 
-Missing a skill? Edit `skills/REQUESTS.md` or open an issue
+**Missing a skill?** Edit `skills/REQUESTS.md` or open an issue
 
 ## License
 

hooks/session-start.sh

@@ -1,15 +1,37 @@
 #!/usr/bin/env bash
 # SessionStart hook for superpowers plugin
 
-# Create data directory
-mkdir -p ~/.superpowers
+set -euo pipefail
+
+# Run personal superpowers setup
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+setup_output=$("${SCRIPT_DIR}/setup-personal-superpowers.sh" 2>&1 || echo "setup_failed=true")
+
+# Use same directory resolution as setup script
+SUPERPOWERS_DIR="${PERSONAL_SUPERPOWERS_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/superpowers}"
+
+# Check if GitHub CLI is available and setup succeeded
+github_recommendation=""
+if echo "$setup_output" | grep -q "github_cli_available=true"; then
+    if [[ ! -d "$SUPERPOWERS_DIR/.git" ]]; then
+        # This should not happen, but handle gracefully
+        github_recommendation=""
+    else
+        # Check if remote already exists
+        if ! (cd "$SUPERPOWERS_DIR" && git remote get-url origin &>/dev/null); then
+            github_recommendation="\n\n💡 Want to share your personal skills on GitHub? Superpowers are best when everyone can learn from them! I can create a 'personal-superpowers' repo for you."
+        fi
+    fi
+elif echo "$setup_output" | grep -q "setup_failed=true"; then
+    github_recommendation="\n\n⚠️  Personal superpowers setup encountered an issue. Please file a bug at https://github.com/obra/superpowers/issues"
+fi
 
 # Output context injection as JSON
 cat <<EOF
 {
   "hookSpecificOutput": {
     "hookEventName": "SessionStart",
-    "additionalContext": "<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**RIGHT NOW, go read**: @${CLAUDE_PLUGIN_ROOT}/skills/getting-started/SKILL.md\n</EXTREMELY_IMPORTANT>"
+    "additionalContext": "<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**RIGHT NOW, go read**: @${CLAUDE_PLUGIN_ROOT}/skills/getting-started/SKILL.md${github_recommendation}\n</EXTREMELY_IMPORTANT>"
   }
 }
 EOF

hooks/setup-personal-superpowers.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Setup script for personal superpowers directory
+# Creates personal superpowers directory with git repo for personal skills
+
+set -euo pipefail
+
+# Use PERSONAL_SUPERPOWERS_DIR if set, otherwise XDG_CONFIG_HOME/superpowers, otherwise ~/.config/superpowers
+SUPERPOWERS_DIR="${PERSONAL_SUPERPOWERS_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/superpowers}"
+SKILLS_DIR="${SUPERPOWERS_DIR}/skills"
+
+# Check if already set up
+if [[ -d "${SUPERPOWERS_DIR}/.git" ]] && [[ -d "${SKILLS_DIR}" ]]; then
+    # Already set up, nothing to do
+    exit 0
+fi
+
+# Create directory structure
+mkdir -p "${SKILLS_DIR}"
+
+# Create .gitignore
+cat > "${SUPERPOWERS_DIR}/.gitignore" <<'EOF'
+# Superpowers local data
+search-log.jsonl
+conversation-index/
+conversation-archive/
+EOF
+
+# Create README
+cat > "${SUPERPOWERS_DIR}/README.md" <<'EOF'
+# My Personal Superpowers
+
+Personal skills and techniques for Claude Code.
+
+Learn more about Superpowers: https://github.com/obra/superpowers
+EOF
+
+# Initialize git repo if not already initialized
+if [[ ! -d "${SUPERPOWERS_DIR}/.git" ]]; then
+    cd "${SUPERPOWERS_DIR}"
+    git init -q
+    git add .gitignore README.md
+    git commit -q -m "Initial commit: Personal superpowers setup"
+fi
+
+# Check for gh and recommend GitHub setup
+if command -v gh &> /dev/null; then
+    echo "github_cli_available=true"
+else
+    echo "github_cli_available=false"
+fi
+
+exit 0

skills/INDEX.md

@@ -1,28 +0,0 @@
-# Claude Superpowers
-
-Your skills library of proven techniques, patterns, and tools.
-
-## First Time Here?
-
-**Read this first:** skills/getting-started - Introduction to the skills library and how to use it
-
-## Quick Start
-
-**Starting a task?** Check the relevant category below.
-**Encountering a problem?** Search with: `${CLAUDE_PLUGIN_ROOT}/skills/getting-started/skills-search keyword`
-**Not sure?** Ask your human partner: "Do I have a skill for X?"
-
-## Categories
-
-- skills/testing - Writing reliable, maintainable tests (TDD, async testing, anti-patterns)
-- skills/debugging - Finding and fixing bugs systematically (root cause tracing, verification)
-- skills/collaboration - Working with other agents and developers (brainstorming, planning, code review)
-- skills/meta - Using, creating, and testing skills
-
-## Navigation
-
-Each category INDEX shows available skills with descriptions. Load the category relevant to your current work.
-
-## Creating New Skills
-
-See skills/meta/creating-skills for guidelines on documenting new techniques.

skills/collaboration/INDEX.md

@@ -1,25 +0,0 @@
-# Collaboration Skills
-
-Working effectively with other agents and developers.
-
-## Available Skills
-
-- skills/collaboration/brainstorming - Interactive idea refinement using Socratic method to develop fully-formed designs. Use when your human partner has new idea to explore. Before writing implementation plans.
-
-- skills/collaboration/writing-plans - Create detailed implementation plans with bite-sized tasks for engineers with zero codebase context. Use after brainstorming/design is complete. Before implementation begins.
-
-- skills/collaboration/using-git-worktrees - Create isolated git worktrees with smart directory selection and safety verification. Use when starting feature implementation in isolation. When brainstorming transitions to code. Before executing plans.
-
-- skills/collaboration/executing-plans - Execute detailed plans in batches with review checkpoints. Use when have complete implementation plan to execute. When implementing in separate session from planning.
-
-- skills/collaboration/subagent-driven-development - Execute plan by dispatching fresh subagent per task with code review between tasks. Alternative to executing-plans when staying in same session. Use when tasks are independent. When want fast iteration with review checkpoints.
-
-- skills/collaboration/finishing-a-development-branch - Complete feature development with structured options for merge, PR, or cleanup. Use after completing implementation. When all tests passing. At end of executing-plans or subagent-driven-development.
-
-- skills/collaboration/remembering-conversations - Search previous Claude Code conversations for facts, patterns, decisions, and context using semantic or text search. Use when your human partner mentions "we discussed this before". When debugging similar issues. When looking for architectural decisions or code patterns from past work. Before reinventing solutions. When searching for git SHAs or error messages.
-
-- skills/collaboration/dispatching-parallel-agents - Use multiple Claude agents to investigate and fix independent problems concurrently. Use when you have 3+ unrelated failures that can be debugged in parallel.
-
-- skills/collaboration/requesting-code-review - Dispatch code-reviewer subagent to review implementation against plan before proceeding. Use after completing task. After major feature. Before merging. When executing plans (after each task).
-
-- skills/collaboration/receiving-code-review - Receive and act on code review feedback with technical rigor, not performative agreement or blind implementation. Use when receiving feedback from your human partner or external reviewers. Before implementing review suggestions. When feedback seems wrong or unclear.

skills/debugging/INDEX.md

@@ -1,13 +0,0 @@
-# Debugging Skills
-
-Techniques for finding and fixing bugs systematically.
-
-## Available Skills
-
-- skills/debugging/defense-in-depth - Validate at every layer data passes through to make bugs impossible. Use when invalid data causes problems deep in call stack.
-
-- skills/debugging/root-cause-tracing - Trace bugs backward through call stack to find original trigger. Use when bugs appear deep in execution and you need to find where they originate. Includes bisection script for finding test pollution.
-
-- skills/debugging/systematic-debugging - Four-phase debugging framework that ensures root cause investigation before attempting fixes. Use when encountering any technical issue, bug, or test failure. Especially critical when under time pressure or tempted to quick-fix.
-
-- skills/debugging/verification-before-completion - Never claim work is complete, tests pass, or bugs are fixed without running actual verification commands. Use before claiming complete, fixed, working, passing, clean, or ready. Before expressing satisfaction with your work. Before committing or creating PRs. When tempted to declare success.

skills/getting-started/SKILL.md

@@ -1,13 +1,17 @@
 ---
 name: Getting Started with Skills
-description: Skills wiki intro - mandatory workflows, search tool, brainstorming triggers
+description: Skills wiki intro - mandatory workflows, search tool, brainstorming triggers, personal skills
 when_to_use: Read this FIRST at start of each conversation when skills are active
-version: 2.0.0
+version: 3.0.0
 ---
 
 # Getting Started with Skills
 
-Your personal wiki of proven techniques, patterns, and tools at `${CLAUDE_PLUGIN_ROOT}/skills/`.
+Two skill libraries work together:
+- **Core skills** at `${CLAUDE_PLUGIN_ROOT}/skills/` (from plugin)
+- **Personal skills** at `~/.config/superpowers/skills/` (yours to create and share)
+
+Personal skills shadow core skills when names match.
 
 ## Just Read This Guide?
 
@@ -28,7 +32,8 @@ ${CLAUDE_PLUGIN_ROOT}/skills/getting-started/list-skills
 - Load with Read tool only when needed
 
 **When you see skill references in documentation:**
-- `skills/path/name` → Use Read tool on `${CLAUDE_PLUGIN_ROOT}/skills/path/name/SKILL.md`
+- `skills/path/name` → Check personal first (`~/.config/superpowers/skills/path/name/SKILL.md`)
+- If not found, check core (`${CLAUDE_PLUGIN_ROOT}/skills/path/name/SKILL.md`)
 - Load supporting files only when implementing
 
 ## Mandatory Workflow 1: Brainstorming Before Coding
@@ -115,14 +120,7 @@ You: Searching past conversations...
 
 **Why:** Checklists without TodoWrite tracking = steps get skipped. Every time.
 
-**Examples:** TDD (write test, watch fail, implement, verify), Systematic Debugging (4 phases), Creating Skills (RED-GREEN-REFACTOR)
-
-## Navigation
-
-Really, try skills-search first.
-
-**Categories:** skills/INDEX.md → testing, debugging, coding, architecture, collaboration, meta
-**Individual skill:** Load from category INDEX
+**Examples:** TDD (write test, watch fail, implement, verify), Systematic Debugging (4 phases), Writing Skills (RED-GREEN-REFACTOR)
 
 ## How to Read a Skill
 
@@ -159,13 +157,15 @@ Your human partner's specific instructions describe WHAT to do, not HOW.
 
 **Red flags:** "Instruction was specific" • "Seems simple" • "Workflow is overkill"
 
-## Creating and Updating Skills
+## Writing and Sharing Skills
+
+**All personal skills are written to `~/.config/superpowers/skills/`**
 
-**Before creating OR editing ANY skill:**
+**Before writing ANY skill:**
 
 1. **STOP** - Even if your human partner gave specific instructions
-2. **Read skills/meta/creating-skills**
-3. **Check in** - "You asked me to edit [skill]. Should I follow creating-skills process or make the change?"
+2. **Read skills/meta/writing-skills**
+3. **Follow the TDD process** - No skill without failing test first
 
 **Your human partner's specific instruction is NOT implicit permission to skip the process.**
 
@@ -173,11 +173,14 @@ Your human partner's specific instructions describe WHAT to do, not HOW.
 - "Just a small addition"
 - "Instruction was specific, so I can proceed"
 
-**All of these mean: STOP and check in first.**
+**All of these mean: STOP and follow writing-skills process.**
 
-Found something valuable? See skills/meta/creating-skills
+**Want to share a skill with everyone?**
+- See skills/meta/sharing-skills for how to contribute to core superpowers
 
-Want a skill that doesn't exist? Edit skills/REQUESTS.md (at ${CLAUDE_PLUGIN_ROOT}/skills/REQUESTS.md)
+**Want a skill that doesn't exist?**
+- Write it yourself (see skills/meta/writing-skills) and share it!
+- Or open an issue at https://github.com/obra/superpowers/issues
 
 ## Summary
 

skills/getting-started/list-skills

@@ -1,22 +1,50 @@
 #!/usr/bin/env bash
 # list-skills - Show all available skill names without descriptions
 # For Claude to quickly see what exists before searching
+# Searches personal skills first, then core skills (personal shadows core)
 
 set -euo pipefail
 
-# Detect if running from repo or installed location
+# Detect core skills directory (repo or installed location)
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 if [[ "$SCRIPT_DIR" == *"/.claude/plugins/cache/"* ]]; then
     # Installed as plugin
-    SKILLS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+    CORE_SKILLS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 else
     # Running from repo
-    SKILLS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+    CORE_SKILLS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 fi
 
-# Find all SKILL.md files and extract their paths
-find "$SKILLS_DIR" -name "SKILL.md" -type f | \
-    sed "s|$SKILLS_DIR/||; s|/SKILL.md||" | \
-    sort
+# Use PERSONAL_SUPERPOWERS_DIR if set, otherwise XDG_CONFIG_HOME/superpowers, otherwise ~/.config/superpowers
+PERSONAL_SUPERPOWERS_DIR="${PERSONAL_SUPERPOWERS_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/superpowers}"
+PERSONAL_SKILLS_DIR="${PERSONAL_SUPERPOWERS_DIR}/skills"
+
+# Collect all skill paths with deduplication
+declare -A seen_skills
+all_skills=()
+
+# Personal skills first (take precedence)
+if [[ -d "$PERSONAL_SKILLS_DIR" ]]; then
+    while IFS= read -r file; do
+        skill_path="${file#$PERSONAL_SKILLS_DIR/}"
+        skill_path="${skill_path%/SKILL.md}"
+        if [[ -n "$skill_path" ]]; then
+            seen_skills["$skill_path"]=1
+            all_skills+=("$skill_path")
+        fi
+    done < <(find "$PERSONAL_SKILLS_DIR" -name "SKILL.md" -type f 2>/dev/null || true)
+fi
+
+# Core skills (only if not shadowed by personal)
+while IFS= read -r file; do
+    skill_path="${file#$CORE_SKILLS_DIR/}"
+    skill_path="${skill_path%/SKILL.md}"
+    if [[ -n "$skill_path" ]] && [[ -z "${seen_skills[$skill_path]:-}" ]]; then
+        all_skills+=("$skill_path")
+    fi
+done < <(find "$CORE_SKILLS_DIR" -name "SKILL.md" -type f 2>/dev/null || true)
+
+# Sort and output
+printf "%s\n" "${all_skills[@]}" | sort
 
 exit 0

skills/getting-started/skills-search

@@ -1,20 +1,24 @@
 #!/usr/bin/env bash
 # skills-search - Find relevant skills using grep patterns
 # Logs all searches for gap analysis (gardening skill processes the log)
+# Searches personal skills first, then core skills (personal shadows core)
 
 set -euo pipefail
 
-# Detect if running from repo or installed location
+# Detect core skills directory (repo or installed location)
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-if [[ "$SCRIPT_DIR" == *"/.claude/skills/getting-started" ]]; then
-    # Installed location
-    SKILLS_DIR="${HOME}/.claude/skills"
+if [[ "$SCRIPT_DIR" == *"/.claude/plugins/cache/"* ]]; then
+    # Installed as plugin
+    CORE_SKILLS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 else
     # Running from repo
-    SKILLS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+    CORE_SKILLS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 fi
 
-LOG_FILE="${HOME}/.superpowers/search-log.jsonl"
+# Use PERSONAL_SUPERPOWERS_DIR if set, otherwise XDG_CONFIG_HOME/superpowers, otherwise ~/.config/superpowers
+PERSONAL_SUPERPOWERS_DIR="${PERSONAL_SUPERPOWERS_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/superpowers}"
+PERSONAL_SKILLS_DIR="${PERSONAL_SUPERPOWERS_DIR}/skills"
+LOG_FILE="${PERSONAL_SUPERPOWERS_DIR}/search-log.jsonl"
 
 # Show usage if no arguments
 if [[ $# -eq 0 ]]; then
@@ -40,16 +44,51 @@ timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 query="$*"
 echo "{\"timestamp\":\"$timestamp\",\"query\":\"$query\"}" >> "$LOG_FILE" 2>/dev/null || true
 
-# Search all SKILL.md files - both content AND path names
-# Content search: grep file contents
-content_matches=$(grep -E -r "$@" "$SKILLS_DIR/" --include="SKILL.md" -l 2>/dev/null || true)
+# Search both personal and core skills directories
+# Personal skills take precedence (searched first)
+
+# Content search: grep file contents from both locations
+content_matches_personal=""
+content_matches_core=""
+if [[ -d "$PERSONAL_SKILLS_DIR" ]]; then
+    content_matches_personal=$(grep -E -r "$@" "$PERSONAL_SKILLS_DIR/" --include="SKILL.md" -l 2>/dev/null || true)
+fi
+content_matches_core=$(grep -E -r "$@" "$CORE_SKILLS_DIR/" --include="SKILL.md" -l 2>/dev/null || true)
 
 # Filename search: find all SKILL.md paths, then grep the paths themselves
-all_skills=$(find "$SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null || true)
-path_matches=$(echo "$all_skills" | grep -E "$@" 2>/dev/null || true)
+all_skills_personal=""
+all_skills_core=""
+if [[ -d "$PERSONAL_SKILLS_DIR" ]]; then
+    all_skills_personal=$(find "$PERSONAL_SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null || true)
+fi
+all_skills_core=$(find "$CORE_SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null || true)
+
+path_matches_personal=$(echo "$all_skills_personal" | grep -E "$@" 2>/dev/null || true)
+path_matches_core=$(echo "$all_skills_core" | grep -E "$@" 2>/dev/null || true)
+
+# Combine all matches
+all_matches=$(printf "%s\n%s\n%s\n%s" "$content_matches_personal" "$content_matches_core" "$path_matches_personal" "$path_matches_core" | grep -v '^$' || true)
+
+# Deduplicate by skill path (personal shadows core)
+declare -A seen_skills
+results=""
+while IFS= read -r file; do
+    # Extract skill path relative to its base directory
+    if [[ "$file" == "$PERSONAL_SKILLS_DIR"* ]]; then
+        skill_path="${file#$PERSONAL_SKILLS_DIR/}"
+    else
+        skill_path="${file#$CORE_SKILLS_DIR/}"
+    fi
+    skill_path="${skill_path%/SKILL.md}"
+
+    # Only include if we haven't seen this skill path yet
+    if [[ -z "${seen_skills[$skill_path]:-}" ]]; then
+        seen_skills["$skill_path"]=1
+        results="${results}${file}"$'\n'
+    fi
+done <<< "$all_matches"
 
-# Combine and deduplicate
-results=$(printf "%s\n%s" "$content_matches" "$path_matches" | sort -u | grep -v '^$' || true)
+results=$(echo "$results" | grep -v '^$' | sort -u || true)
 
 if [[ -z "$results" ]]; then
     echo "❌ No skills found matching: $*"
@@ -68,7 +107,12 @@ echo "$results" | while read -r file; do
     description=$(grep "^description:" "$file" 2>/dev/null | sed 's/description: *//' || echo "")
 
     # Get relative path without @ prefix or /SKILL.md suffix
-    rel_path="${file#$SKILLS_DIR/}"
+    # Handle both personal and core skills
+    if [[ "$file" == "$PERSONAL_SKILLS_DIR"* ]]; then
+        rel_path="${file#$PERSONAL_SKILLS_DIR/}"
+    else
+        rel_path="${file#$CORE_SKILLS_DIR/}"
+    fi
     rel_path="skills/${rel_path%/SKILL.md}"
 
     if [[ -n "$description" ]]; then

skills/meta/INDEX.md

@@ -1,14 +0,0 @@
-# Meta Skills
-
-Skills about skills - how to create and use the skills system.
-
-## Available Skills
-
-- skills/meta/installing-skills - Fork, clone, and symlink clank repo to ~/.claude/skills. Use for initial setup, installing clank for the first time.
-
-- skills/meta/creating-skills - How to create effective skills for future Claude instances. Use when you discover a technique, pattern, or tool worth documenting for reuse.
-
-- skills/meta/testing-skills-with-subagents - Iteratively test and bulletproof skills using pressure scenarios and rationalization analysis. Use after writing skills that enforce discipline or rules, before deploying skills agents might want to bypass.
-
-- skills/meta/gardening-skills-wiki - Maintain skills wiki health with automated checks for broken links, naming consistency, and INDEX coverage. Use when adding/removing skills, reorganizing categories, or for periodic maintenance.
-

skills/meta/installing-skills/CLAUDE_MD_PREAMBLE.md

@@ -1,14 +0,0 @@
-<EXTREMELY_IMPORTANT>
-You have a personal skills wiki at ~/.claude/skills/ with proven techniques, patterns, and tools that give you new capabilities.
-
-STOP. Before doing ANYTHING else in this conversation, read this file: @skills/getting-started/SKILL.md
-
-That file tells you how to find and use your skills.
-
-ONLY after reading getting-started, are you allowed to proceed with the user's request.
-
-When your partner proposes building or creating something, immediately use skills/collaboration/brainstorming
-
-CRITICAL: If a skill exists for your task, you MUST use it - even if you think you're already good at that. You're not. The skill prevents mistakes you don't know you make. SKILLS EXIST AND YOU DIDN'T USE THEM = FAILED TASK.
-
-</EXTREMELY_IMPORTANT>

skills/meta/installing-skills/SKILL.md

@@ -1,224 +0,0 @@
----
-name: Installing Skills System
-description: Fork, clone to ~/.clank, run installer, edit CLAUDE.md
-when_to_use: Initial setup, installing clank for the first time
-version: 2.0.0
-languages: bash
----
-
-# Installing Skills System
-
-## Overview
-
-Installs the clank skills repository to `~/.clank/clank` and configures Claude to use it.
-
-**For Claude agents:** Follow the "Installation Steps for Claude" section below.
-
-**For humans:** Follow the "Quick Install" section.
-
-## Installation Steps for Claude
-
-When instructed to install clank, follow these steps exactly:
-
-### Step 1: Clone Repository
-
-**With GitHub CLI (if available):**
-```bash
-mkdir -p ~/.clank
-cd ~/.clank
-gh repo fork obra/clank --clone --remote-name upstream
-```
-
-**Without GitHub CLI:**
-```bash
-mkdir -p ~/.clank
-cd ~/.clank
-git clone https://github.com/obra/clank.git
-```
-
-### Step 2: Run Installer
-
-```bash
-cd ~/.clank/clank
-./skills/meta/installing-skills/install.sh
-```
-
-This creates symlinks for skills and commands.
-
-### Step 3: Update CLAUDE.md
-
-Use the Edit tool to add this XML section to the very beginning of `~/.claude/CLAUDE.md`:
-
-```xml
-<EXTREMELY_IMPORTANT>
-You have a personal skills wiki at ~/.claude/skills/ with proven techniques, patterns, and tools that give you new capabilities.
-
-STOP. Before doing ANYTHING else in this conversation, read this file: skills/getting-started
-
-That file tells you how to find and use your skills.
-
-ONLY after reading getting-started, are you allowed to proceed with the user's request.
-
-CRITICAL: If a skill exists for your task, you MUST use it - even if you think you're already good at that. You're not. The skill prevents mistakes you don't know you make. SKILLS EXIST AND YOU DIDN'T USE THEM = FAILED TASK.
-
-</EXTREMELY_IMPORTANT>
-```
-
-### Step 4: Verify Installation
-
-```bash
-ls -la ~/.claude/skills
-ls -la ~/.claude/commands
-~/.claude/skills/getting-started/skills-search 'test.*driven'
-```
-
-### Step 5: Restart
-
-Tell your human partner: "Installation complete. Please restart your Claude session to pick up the new CLAUDE.md configuration."
-
-## Quick Install (for humans)
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/obra/clank/main/skills/meta/installing-skills/install.sh | bash
-# Then manually add CLAUDE.md section from Step 3 above
-```
-
-## What install.sh Does
-
-1. **Validates** you're running from clank repo root (expects ~/.clank/clank)
-2. **Backs up** existing `~/.claude/skills` (if exists) to timestamped backup
-3. **Creates skills symlink**: `~/.claude/skills` → `~/.clank/clank/skills`
-4. **Symlinks individual commands** from `~/.clank/clank/commands/*.md` to `~/.claude/commands/`
-5. **Verifies** tools available (skills-search at `~/.claude/skills/getting-started/skills-search`)
-6. **Prints** CLAUDE.md XML snippet to add and verification steps
-
-## Verification
-
-After installation, verify it worked:
-
-```bash
-# Should show symlink to ~/.clank/clank/skills
-ls -la ~/.claude/skills
-
-# Should show individual command symlinks
-ls -la ~/.claude/commands/
-
-# Test skills-search tool
-~/.claude/skills/getting-started/skills-search 'test.*driven'
-```
-
-## What Gets Installed
-
-**Skills** (`~/.claude/skills/`):
-- Library of proven techniques, patterns, and tools
-- Referenced with `@` syntax in code and documentation
-- Searchable with `skills-search` tool
-
-**Commands** (`~/.claude/commands/`):
-- Individual symlinks to clank command files
-- Slash commands for Claude (`/brainstorm`, `/write-plan`, `/execute-plan`)
-- Each command references a skill using `@` syntax
-- Makes common workflows one command away
-
-**Tools** (`~/.claude/skills/getting-started/`):
-- `skills-search` - Find relevant skills using grep patterns
-- Logs failed searches for gap analysis
-
-## Why Fork?
-
-Forking lets you:
-- **Customize** skills and commands for your workflow
-- **Contribute** improvements back via PR (see skills/contributing-skills)
-- **Stay synced** with upstream updates (`git pull upstream main`)
-- **Track** your customizations in version control
-
-## Configure CLAUDE.md
-
-After installation, edit your `~/.claude/CLAUDE.md` and add this section:
-
-```xml
-<extremely_important_skills_library>
-You have a personal skills wiki at `~/.claude/skills/` with proven techniques, patterns, and tools that give you new capabilities.
-
-STOP. Before doing ANYTHING else in this conversation, read this file: `skills/getting-started`
-
-That file tells you:
-- Which phrases trigger brainstorming automatically (like "I've got an idea", "Let's make...")
-- How to search for skills before ANY task
-- When to announce which skill you're using
-
-After reading getting-started, proceed with the user's request.
-
-CRITICAL: If a skill exists for your task, you MUST use it - even if you think you're already good at that. You're not. The skill prevents mistakes you don't know you make. SKILLS EXIST AND YOU DIDN'T USE THEM = FAILED TASK.
-</extremely_important_skills_library>
-```
-
-This enables:
-- Automatic skill discovery before every task
-- Mandatory skill usage enforcement
-- Gap tracking for missing skills (logged searches)
-
-## Updating Skills
-
-After initial install, update with:
-
-```bash
-cd ~/.clank/clank
-git pull origin main    # Pull your changes
-git pull upstream main  # Pull upstream updates (if configured)
-```
-
-The symlinks stay valid - no need to reinstall.
-
-## Troubleshooting
-
-### "Error: Not running from clank repository root"
-
-The script expects to be run from `~/.clank/clank/`. Clone it first:
-```bash
-mkdir -p ~/.clank
-cd ~/.clank
-gh repo fork obra/clank --clone
-cd clank
-./skills/meta/installing-skills/install.sh
-```
-
-### "~/.claude/skills already exists"
-
-The installer automatically backs it up with timestamp. Check backups:
-```bash
-ls -la ~/.claude/skills.backup.*
-```
-
-### Symlinks broken
-
-Remove and reinstall:
-```bash
-rm ~/.claude/skills
-rm ~/.claude/commands/*.md  # Remove individual command symlinks
-cd ~/.clank/clank
-./skills/meta/installing-skills/install.sh
-```
-
-## Uninstalling
-
-```bash
-# Remove symlinks
-rm ~/.claude/skills
-rm ~/.claude/commands/brainstorm.md
-rm ~/.claude/commands/write-plan.md
-rm ~/.claude/commands/execute-plan.md
-
-# Restore backup if desired
-mv ~/.claude/skills.backup.YYYY-MM-DD-HHMMSS ~/.claude/skills
-
-# Remove from CLAUDE.md
-# Delete the "Skills Library" section from ~/.claude/CLAUDE.md
-
-# Remove cloned repo
-rm -rf ~/.clank/clank
-```
-
-## Implementation
-
-See @install.sh for the installation script.

skills/meta/installing-skills/install.sh

@@ -1,191 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Validate we're running from clank repository root
-validate_clank_repo() {
-  if [[ ! -d "skills/meta/installing-skills" ]]; then
-    echo -e "${RED}Error: Not running from clank repository root${NC}"
-    echo ""
-    echo "Expected to be run from ~/.clank/clank/"
-    echo ""
-    echo "To install clank, clone to ~/.clank first:"
-    echo "  ${GREEN}mkdir -p ~/.clank && cd ~/.clank${NC}"
-    echo "  ${GREEN}gh repo fork obra/clank --clone${NC}"
-    echo "  ${GREEN}cd clank${NC}"
-    echo "  ${GREEN}./skills/meta/installing-skills/install.sh${NC}"
-    exit 1
-  fi
-}
-
-# Get absolute path to clank repo
-get_repo_path() {
-  if [[ "$OSTYPE" == "darwin"* ]]; then
-    # macOS doesn't have realpath by default, use Python
-    python3 -c "import os; print(os.path.realpath('.'))"
-  else
-    realpath .
-  fi
-}
-
-# Backup existing skills directory if it exists
-backup_existing_skills() {
-  local skills_dir="$HOME/.claude/skills"
-
-  if [[ -e "$skills_dir" ]]; then
-    local timestamp=$(date +%Y-%m-%d-%H%M%S)
-    local backup_path="${skills_dir}.backup.${timestamp}"
-
-    echo -e "${YELLOW}Found existing ~/.claude/skills${NC}"
-    echo -e "Backing up to: ${backup_path}"
-
-    mv "$skills_dir" "$backup_path"
-    echo -e "${GREEN}✓${NC} Backup created"
-    echo ""
-  fi
-}
-
-# No need to backup commands - we symlink individual files
-
-# Create skills symlink
-create_symlink() {
-  local repo_path="$1"
-  local skills_source="${repo_path}/skills"
-  local skills_target="$HOME/.claude/skills"
-
-  # Ensure ~/.claude directory exists
-  mkdir -p "$HOME/.claude"
-
-  echo "Creating skills symlink:"
-  echo "  ${skills_target} → ${skills_source}"
-
-  ln -s "$skills_source" "$skills_target"
-  echo -e "${GREEN}✓${NC} Skills symlink created"
-  echo ""
-}
-
-# Symlink individual commands
-symlink_commands() {
-  local repo_path="$1"
-  local commands_source="${repo_path}/commands"
-  local commands_target="$HOME/.claude/commands"
-
-  # Check if commands directory exists in repo
-  if [[ ! -d "$commands_source" ]]; then
-    echo -e "${YELLOW}No commands directory in repo, skipping${NC}"
-    echo ""
-    return
-  fi
-
-  # Ensure ~/.claude/commands exists
-  mkdir -p "$commands_target"
-
-  echo "Symlinking commands:"
-
-  # Symlink each command file
-  for cmd in "$commands_source"/*.md; do
-    if [[ -f "$cmd" && "$(basename "$cmd")" != "README.md" ]]; then
-      cmd_name=$(basename "$cmd")
-      ln -sf "$cmd" "$commands_target/$cmd_name"
-      echo "  ${cmd_name}"
-    fi
-  done
-
-  echo -e "${GREEN}✓${NC} Commands symlinked"
-  echo ""
-}
-
-# Verify tools exist
-verify_tools() {
-  local skills_dir="$HOME/.claude/skills"
-  local skills_search="${skills_dir}/getting-started/skills-search"
-
-  if [[ -x "$skills_search" ]]; then
-    echo -e "${GREEN}✓${NC} skills-search tool available"
-    echo ""
-  fi
-}
-
-# Verify installation
-verify_installation() {
-  local skills_dir="$HOME/.claude/skills"
-  local commands_dir="$HOME/.claude/commands"
-
-  echo "Verifying installation..."
-
-  # Verify skills
-  if [[ ! -L "$skills_dir" ]]; then
-    echo -e "${RED}✗${NC} ~/.claude/skills is not a symlink"
-    exit 1
-  fi
-
-  if [[ ! -f "$skills_dir/INDEX.md" ]]; then
-    echo -e "${RED}✗${NC} INDEX.md not found in ~/.claude/skills"
-    exit 1
-  fi
-
-  echo -e "${GREEN}✓${NC} Skills verified"
-
-  # Verify commands were symlinked
-  if [[ -d "$commands_dir" ]]; then
-    cmd_count=$(find "$commands_dir" -type l -name "*.md" 2>/dev/null | wc -l)
-    if [[ $cmd_count -gt 0 ]]; then
-      echo -e "${GREEN}✓${NC} Commands verified ($cmd_count symlinked)"
-    fi
-  fi
-
-  echo ""
-}
-
-# Print success message
-print_success() {
-  local repo_path="$1"
-
-  echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-  echo -e "${GREEN}Installation complete!${NC}"
-  echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-  echo ""
-  echo -e "${YELLOW}NEXT STEP: Update ~/.claude/CLAUDE.md${NC}"
-  echo ""
-  echo "Add this to your CLAUDE.md:"
-  echo ""
-  cat "${repo_path}/skills/meta/installing-skills/CLAUDE_MD_PREAMBLE.md"
-  echo ""
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo ""
-  echo "Verify installation:"
-  echo "  ${GREEN}ls -la ~/.claude/skills${NC}"
-  echo "  ${GREEN}ls ~/.claude/commands/${NC}"
-  echo "  ${GREEN}~/.claude/skills/getting-started/skills-search 'test.*driven'${NC}"
-  echo ""
-  echo "Repository location: ${repo_path}"
-  echo ""
-}
-
-# Main installation flow
-main() {
-  echo ""
-  echo "Clank Installation"
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo ""
-
-  validate_clank_repo
-
-  local repo_path=$(get_repo_path)
-  echo "Repository path: ${repo_path}"
-  echo ""
-
-  backup_existing_skills
-  create_symlink "$repo_path"
-  symlink_commands "$repo_path"
-  verify_tools "$repo_path"
-  verify_installation
-  print_success "$repo_path"
-}
-
-main "$@"

skills/meta/setting-up-personal-superpowers/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: Setting Up Personal Superpowers
+description: Automatic setup of ~/.config/superpowers/ for personal skills, optional GitHub repo creation
+when_to_use: Runs automatically on first session. Reference when helping users with personal skills setup.
+version: 1.0.0
+languages: bash
+---
+
+# Setting Up Personal Superpowers
+
+## Overview
+
+Personal superpowers directory is automatically set up on your first session. It provides a place to create and manage your own skills alongside the core superpowers library.
+
+**Default location:** `~/.config/superpowers/`
+
+**Customizable via:**
+- `PERSONAL_SUPERPOWERS_DIR` environment variable (highest priority)
+- `XDG_CONFIG_HOME` environment variable (if set, uses `$XDG_CONFIG_HOME/superpowers`)
+- Falls back to `~/.config/superpowers`
+
+**Structure:**
+```
+~/.config/superpowers/
+  ├── .git/                # Git repository
+  ├── .gitignore           # Ignores logs and indexes
+  ├── README.md            # About your personal superpowers
+  ├── skills/              # Your personal skills
+  │   └── your-skill/
+  │       └── SKILL.md
+  ├── search-log.jsonl     # Skill search history (not tracked)
+  └── conversation-index/  # Conversation search index (not tracked)
+```
+
+## How It Works
+
+The SessionStart hook runs `hooks/setup-personal-superpowers.sh` which:
+
+1. Checks if `~/.config/superpowers/.git/` and `~/.config/superpowers/skills/` exist
+2. If not, creates directory structure
+3. Initializes git repository
+4. Creates `.gitignore`, `README.md`
+5. Makes initial commit
+6. Checks for `gh` CLI availability
+
+If GitHub CLI is available and no remote exists, you'll see a recommendation to create a public GitHub repo.
+
+## Creating GitHub Repository
+
+When prompted, you can create a public `personal-superpowers` repo:
+
+```bash
+cd ~/.config/superpowers
+gh repo create personal-superpowers --public --source=. --push
+gh repo edit --add-topic superpowers
+```
+
+**Why public?** Superpowers are best when everyone can learn from them!
+
+**Privacy:** If you prefer private or local-only:
+- **Private:** Use `--private` instead of `--public`
+- **Local-only:** Just use the local git repo without pushing to GitHub
+
+## What Gets Tracked
+
+**.gitignore includes:**
+- `search-log.jsonl` - Your skill search history
+- `conversation-index/` - Conversation search index
+- `conversation-archive/` - Archived conversations
+
+**Everything else is tracked**, including:
+- Your personal skills in `skills/`
+- README.md
+- Any additional documentation you add
+
+## Personal vs Core Skills
+
+**Search order:**
+1. `~/.config/superpowers/skills/` (personal)
+2. `${CLAUDE_PLUGIN_ROOT}/skills/` (core)
+
+**Personal skills shadow core skills** - if you have `~/.config/superpowers/skills/testing/test-driven-development/SKILL.md`, it will be used instead of the core version.
+
+The `list-skills` and `skills-search` tools automatically search both locations with deduplication.
+
+## Writing Skills
+
+See skills/meta/writing-skills for how to create new skills.
+
+All personal skills are written to `~/.config/superpowers/skills/`.
+
+## Sharing Skills
+
+See skills/meta/sharing-skills for how to contribute skills back to the core superpowers repository.
+
+## Custom Location
+
+To use a different location for your personal superpowers:
+
+```bash
+# In your shell rc file (.bashrc, .zshrc, etc)
+export PERSONAL_SUPERPOWERS_DIR="$HOME/my-superpowers"
+
+# Or use XDG_CONFIG_HOME
+export XDG_CONFIG_HOME="$HOME/.local/config"  # Will use $HOME/.local/config/superpowers
+```
+
+## Manual Setup
+
+If auto-setup fails or you need to set up manually:
+
+```bash
+# Use your preferred location
+SUPERPOWERS_DIR="${PERSONAL_SUPERPOWERS_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/superpowers}"
+mkdir -p "$SUPERPOWERS_DIR/skills"
+cd "$SUPERPOWERS_DIR"
+git init
+cat > .gitignore <<'EOF'
+search-log.jsonl
+conversation-index/
+conversation-archive/
+EOF
+
+cat > README.md <<'EOF'
+# My Personal Superpowers
+
+Personal skills and techniques for Claude Code.
+
+Learn more about Superpowers: https://github.com/obra/superpowers
+EOF
+
+git add .gitignore README.md
+git commit -m "Initial commit: Personal superpowers setup"
+
+# Optional: Create GitHub repo
+gh repo create personal-superpowers --public --source=. --push
+gh repo edit --add-topic superpowers
+```
+
+## Troubleshooting
+
+**Setup failed during SessionStart:**
+File a bug at https://github.com/obra/superpowers/issues
+
+**Personal skills not being found:**
+- Check `~/.config/superpowers/skills/` exists
+- Verify skill has `SKILL.md` file
+- Run `${CLAUDE_PLUGIN_ROOT}/skills/getting-started/list-skills` to see if it appears
+
+**GitHub push failed:**
+- Check `gh auth status`
+- Verify repo was created: `gh repo view personal-superpowers`
+- Try manual push: `cd ~/.config/superpowers && git push -u origin main`
+
+## Multi-CLI Support
+
+The personal superpowers directory is CLI-agnostic. It works with:
+- Claude Code (current)
+- OpenAI Codex CLI (future)
+- Gemini CLI (future)
+
+Each CLI installs its own base superpowers, but they all read from the same `~/.config/superpowers/skills/` for personal skills.

skills/meta/sharing-skills/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: Sharing Skills
+description: Contribute personal skills back to core superpowers via fork, branch, and PR
+when_to_use: When you have a personal skill that would benefit others and want to contribute it to the core superpowers library
+version: 1.0.0
+languages: bash
+---
+
+# Sharing Skills
+
+## Overview
+
+Contribute personal skills from `~/.config/superpowers/skills/` back to the core superpowers repository.
+
+**Workflow:** Fork → Clone to temp → Sync → Branch → Copy 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
+- Personal skill exists in `~/.config/superpowers/skills/your-skill/`
+- Skill has been tested (see skills/meta/writing-skills for TDD process)
+
+## Sharing Workflow
+
+### 1. Fork Core Repository
+
+```bash
+# Check if you already have a fork
+gh repo view YOUR_USERNAME/superpowers 2>/dev/null || gh repo fork obra/superpowers
+```
+
+### 2. Clone to Temporary Directory
+
+```bash
+# Create temp directory for contribution
+temp_dir=$(mktemp -d)
+cd "$temp_dir"
+git clone git@github.com:YOUR_USERNAME/superpowers.git
+cd superpowers
+```
+
+### 3. Sync with Upstream
+
+```bash
+# Add upstream if not already added
+git remote add upstream https://github.com/obra/superpowers 2>/dev/null || true
+
+# Fetch and merge latest from upstream
+git fetch upstream
+git checkout main
+git merge upstream/main
+git push origin main
+```
+
+### 4. Create Feature Branch
+
+```bash
+# Branch name: add-skillname-skill
+skill_name="your-skill-name"
+git checkout -b "add-${skill_name}-skill"
+```
+
+### 5. Copy Skill from Personal Repo
+
+```bash
+# Copy skill directory from personal superpowers
+cp -r ~/.config/superpowers/skills/your-skill-name/ superpowers/skills/
+
+# Verify it copied correctly
+ls -la superpowers/skills/your-skill-name/
+```
+
+### 6. Commit Changes
+
+```bash
+# Add and commit
+git add superpowers/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
+)"
+```
+
+### 7. Push to Your Fork
+
+```bash
+git push -u origin "add-${skill_name}-skill"
+```
+
+### 8. Create Pull Request
+
+```bash
+# Create PR using gh CLI
+gh pr create \
+  --repo obra/superpowers \
+  --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
+)"
+```
+
+### 9. Cleanup
+
+```bash
+# Remove temp directory after PR is created
+cd ~
+rm -rf "$temp_dir"
+```
+
+## Complete Example
+
+Here's a complete example of sharing a personal skill called "async-patterns":
+
+```bash
+# 1. Fork if needed
+gh repo view $(gh api user --jq .login)/superpowers 2>/dev/null || gh repo fork obra/superpowers
+
+# 2-3. Clone and sync
+temp_dir=$(mktemp -d) && cd "$temp_dir"
+gh repo clone $(gh api user --jq .login)/superpowers
+cd superpowers
+git remote add upstream https://github.com/obra/superpowers 2>/dev/null || true
+git fetch upstream
+git checkout main
+git merge upstream/main
+git push origin main
+
+# 4. Create branch
+git checkout -b "add-async-patterns-skill"
+
+# 5. Copy skill
+cp -r ~/.config/superpowers/skills/async-patterns/ superpowers/skills/
+
+# 6. Commit
+git add superpowers/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."
+
+# 7. Push
+git push -u origin "add-async-patterns-skill"
+
+# 8. Create PR
+gh pr create \
+  --repo obra/superpowers \
+  --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."
+
+# 9. Cleanup
+cd ~ && rm -rf "$temp_dir"
+```
+
+## After PR is Merged
+
+Once your PR is merged:
+
+**Option 1: Keep personal version**
+- Useful if you want to continue iterating locally
+- Your personal version will shadow the core version
+- Can later delete personal version to use core
+
+**Option 2: Delete personal version**
+```bash
+# Remove from personal repo to use core version
+rm -rf ~/.config/superpowers/skills/your-skill-name/
+cd ~/.config/superpowers
+git add skills/your-skill-name/
+git commit -m "Remove your-skill-name (now in core)"
+git push
+```
+
+## 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 in core"**
+- You're creating a modified version
+- Consider different skill name or shadow the core version in personal repo
+
+**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
+- **skills/meta/setting-up-personal-superpowers** - Initial setup of personal repo

skills/meta/creating-skills/SKILL.md → skills/meta/writing-skills/SKILL.md

@@ -1,16 +1,18 @@
 ---
-name: Creating Skills
+name: Writing Skills
 description: TDD for process documentation - test with subagents before writing, iterate until bulletproof
 when_to_use: When you discover a technique, pattern, or tool worth documenting for reuse. When editing existing skills. When asked to modify skill documentation. When you've written a skill and need to verify it works before deploying.
-version: 4.1.0
+version: 5.0.0
 languages: all
 ---
 
-# Creating Skills
+# Writing Skills
 
 ## Overview
 
-**Creating skills IS Test-Driven Development applied to process documentation.**
+**Writing skills IS Test-Driven Development applied to process documentation.**
+
+**All personal skills are written to `~/.config/superpowers/skills/`** - this is your personal superpowers repository, separate from the core superpowers library.
 
 You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
 
@@ -69,14 +71,16 @@ API docs, syntax guides, tool documentation (office docs)
 
 ## Directory Structure
 
+**All skills are written to `~/.config/superpowers/skills/`:**
+
 ```
-skills/
+~/.config/superpowers/skills/
   skill-name/
     SKILL.md              # Main reference (required)
     supporting-file.*     # Only if needed
 ```
 
-**Flat namespace** - all skills in one searchable location
+**Flat namespace** - all personal skills in one searchable location
 
 **Separate files for:**
 1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax
@@ -527,7 +531,6 @@ helper1, helper2, step3, pattern4
 
 **Do NOT:**
 - Create multiple skills in batch without testing each
-- Update INDEX.md before testing skills
 - Move to next skill before current one is verified
 - Skip testing because "batching is more efficient"
 
@@ -573,7 +576,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 How future Claude finds your skill:
 
 1. **Encounters problem** ("tests are flaky")
-2. **Greps skills** (`grep -r "flaky" ~/.claude/skills/`)
+2. **Searches skills** using `skills-search` tool (checks personal then core)
 3. **Finds SKILL.md** (rich when_to_use matches)
 4. **Scans overview** (is this relevant?)
 5. **Reads patterns** (quick reference table)

skills/testing/INDEX.md

@@ -1,11 +0,0 @@
-# Testing Skills
-
-Skills for writing reliable, maintainable tests.
-
-## Available Skills
-
-- skills/testing/test-driven-development - Red-green-refactor cycle: write failing test first, minimal code to pass, refactor. Mandatory for all features and bugfixes. Use when writing any production code, when you wrote code before tests, when tempted to test after.
-
-- skills/testing/condition-based-waiting - Replace arbitrary timeouts with condition polling for reliable async tests. Use when tests are flaky, timing-dependent, or use setTimeout/sleep.
-
-- skills/testing/testing-anti-patterns - Never test mock behavior, never add test-only methods to production classes, understand dependencies before mocking. Use when writing tests, adding mocks, fixing failing tests. When tempted to assert on mock elements or add cleanup methods to production code.