Merge pull request #2 from obra/personal-superpowers

Add personal superpowers overlay system

.gitignore

@@ -0,0 +1,2 @@
+.worktrees/
+.private-journal/

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:
+Find both personal and core skills before starting any task:
 
 ```bash
-${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'
+${CLAUDE_PLUGIN_ROOT}/scripts/find-skills              # All skills with descriptions
+${CLAUDE_PLUGIN_ROOT}/scripts/find-skills test         # Filter by pattern
+${CLAUDE_PLUGIN_ROOT}/scripts/find-skills 'TDD|debug'  # Regex pattern
 ```
 
 ### 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
 
@@ -113,15 +127,28 @@ ${CLAUDE_PLUGIN_ROOT}/skills/getting-started/skills-search 'refactor'
 
 ### Tools
 
-- **skills-search** - Grep-powered skill discovery
-- **search-conversations** - Semantic search of past Claude sessions
+**In `scripts/` directory:**
+- **find-skills** - Unified skill discovery with descriptions (replaces list-skills + skills-search)
+- **skill-run** - Generic runner for any skill script (searches personal then core)
+
+**Skill-specific tools:**
+- **search-conversations** - Semantic search of past Claude sessions (in remembering-conversations skill)
+
+**Using scripts:**
+```bash
+${CLAUDE_PLUGIN_ROOT}/scripts/find-skills                 # Show all skills
+${CLAUDE_PLUGIN_ROOT}/scripts/find-skills pattern         # Search skills
+${CLAUDE_PLUGIN_ROOT}/scripts/skill-run <path> [args]     # Run any skill script
+```
 
 ## 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** - `find-skills` searches both locations with descriptions
+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 +158,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 creates `~/.superpowers/` for local data:
+The plugin auto-creates your personal superpowers directory on first session.
 
+**Default location:** `~/.config/superpowers/`
+
+**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
 ```
-~/.superpowers/
-├── search-log.jsonl          # Failed skill searches
-└── conversation-index/       # Indexed past conversations (if enabled)
+
+**Structure:**
 ```
+~/.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**Skill tools are at:**\n- find-skills: ${CLAUDE_PLUGIN_ROOT}/scripts/find-skills\n- skill-run: ${CLAUDE_PLUGIN_ROOT}/scripts/skill-run\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

scripts/find-skills

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# find-skills - Find and list skills with descriptions
+# Shows all skills by default, filters by pattern if provided
+# Searches personal superpowers first, then core (personal shadows core)
+
+set -euo pipefail
+
+# Determine directories
+PERSONAL_SUPERPOWERS_DIR="${PERSONAL_SUPERPOWERS_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/superpowers}"
+PERSONAL_SKILLS_DIR="${PERSONAL_SUPERPOWERS_DIR}/skills"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CORE_SKILLS_DIR="${PLUGIN_ROOT}/skills"
+
+LOG_FILE="${PERSONAL_SUPERPOWERS_DIR}/search-log.jsonl"
+
+# Show help
+if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]]; then
+    cat <<'EOF'
+find-skills - Find and list skills with descriptions
+
+USAGE:
+  find-skills              Show all skills with descriptions
+  find-skills PATTERN      Filter skills by grep pattern
+  find-skills --help       Show this help
+
+EXAMPLES:
+  find-skills                        # All skills
+  find-skills test                   # Skills matching "test"
+  find-skills 'test.*driven|TDD'     # Regex pattern
+
+OUTPUT:
+  Each line shows: skill-path - description
+  Personal skills listed first, then core skills
+  Personal skills shadow core skills when paths match
+
+SEARCH:
+  Searches both skill content AND path names.
+  Personal skills at: ~/.config/superpowers/skills/
+  Core skills at: plugin installation directory
+EOF
+    exit 0
+fi
+
+# Get pattern (optional)
+PATTERN="${1:-}"
+
+# Function to extract description from SKILL.md
+get_description() {
+    local file="$1"
+    grep "^description:" "$file" 2>/dev/null | sed 's/description: *//' || echo ""
+}
+
+# Function to get relative skill path
+get_skill_path() {
+    local file="$1"
+    local base_dir="$2"
+    local rel_path="${file#$base_dir/}"
+    echo "${rel_path%/SKILL.md}"
+}
+
+# Collect all matching skills (use simple list for bash 3.2 compatibility)
+seen_skills_list=""
+results=()
+
+# If pattern provided, log the search
+if [[ -n "$PATTERN" ]]; then
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    echo "{\"timestamp\":\"$timestamp\",\"query\":\"$PATTERN\"}" >> "$LOG_FILE" 2>/dev/null || true
+fi
+
+# Search personal skills first
+if [[ -d "$PERSONAL_SKILLS_DIR" ]]; then
+    while IFS= read -r file; do
+        [[ -z "$file" ]] && continue
+
+        skill_path=$(get_skill_path "$file" "$PERSONAL_SKILLS_DIR")
+        description=$(get_description "$file")
+
+        seen_skills_list="${seen_skills_list}${skill_path}"$'\n'
+        results+=("$skill_path|$description")
+    done < <(
+        if [[ -n "$PATTERN" ]]; then
+            # Pattern mode: search content and paths
+            {
+                grep -E -r "$PATTERN" "$PERSONAL_SKILLS_DIR/" --include="SKILL.md" -l 2>/dev/null || true
+                find "$PERSONAL_SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null | grep -E "$PATTERN" 2>/dev/null || true
+            } | sort -u
+        else
+            # Show all
+            find "$PERSONAL_SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null || true
+        fi
+    )
+fi
+
+# Search core skills (only if not shadowed)
+while IFS= read -r file; do
+    [[ -z "$file" ]] && continue
+
+    skill_path=$(get_skill_path "$file" "$CORE_SKILLS_DIR")
+
+    # Skip if shadowed by personal skill
+    echo "$seen_skills_list" | grep -q "^${skill_path}$" && continue
+
+    description=$(get_description "$file")
+    results+=("$skill_path|$description")
+done < <(
+    if [[ -n "$PATTERN" ]]; then
+        # Pattern mode: search content and paths
+        {
+            grep -E -r "$PATTERN" "$CORE_SKILLS_DIR/" --include="SKILL.md" -l 2>/dev/null || true
+            find "$CORE_SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null | grep -E "$PATTERN" 2>/dev/null || true
+        } | sort -u
+    else
+        # Show all
+        find "$CORE_SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null || true
+    fi
+)
+
+# Check if we found anything
+if [[ ${#results[@]} -eq 0 ]]; then
+    if [[ -n "$PATTERN" ]]; then
+        echo "❌ No skills found matching: $PATTERN"
+        echo ""
+        echo "Search logged. If a skill should exist, consider writing it!"
+    else
+        echo "❌ No skills found"
+    fi
+    exit 0
+fi
+
+# Sort and display results
+printf "%s\n" "${results[@]}" | sort | while IFS='|' read -r skill_path description; do
+    if [[ -n "$description" ]]; then
+        echo "skills/$skill_path - $description"
+    else
+        echo "skills/$skill_path"
+    fi
+done
+
+exit 0

scripts/skill-run

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Generic runner for skill scripts
+# Searches personal superpowers first, then core plugin
+#
+# Usage: scripts/skill-run <skill-relative-path> [args...]
+# Example: scripts/skill-run skills/collaboration/remembering-conversations/tool/search-conversations "query"
+
+set -euo pipefail
+
+if [[ $# -eq 0 ]]; then
+    cat <<'EOF'
+Usage: scripts/skill-run <skill-relative-path> [args...]
+
+Runs scripts from skills, checking personal superpowers first, then core.
+
+Examples:
+  scripts/skill-run skills/collaboration/remembering-conversations/tool/search-conversations "query"
+  scripts/skill-run skills/collaboration/remembering-conversations/tool/index-conversations --cleanup
+
+The script will be found at:
+  1. ~/.config/superpowers/<skill-relative-path> (personal, if exists)
+  2. ${CLAUDE_PLUGIN_ROOT}/<skill-relative-path> (core plugin)
+EOF
+    exit 1
+fi
+
+# Get the script path to run
+SCRIPT_PATH="$1"
+shift  # Remove script path from args, leaving remaining args
+
+# Determine directories
+PERSONAL_SUPERPOWERS_DIR="${PERSONAL_SUPERPOWERS_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/superpowers}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Try personal superpowers first
+PERSONAL_SCRIPT="${PERSONAL_SUPERPOWERS_DIR}/${SCRIPT_PATH}"
+if [[ -x "$PERSONAL_SCRIPT" ]]; then
+    exec "$PERSONAL_SCRIPT" "$@"
+fi
+
+# Fall back to core plugin
+CORE_SCRIPT="${PLUGIN_ROOT}/${SCRIPT_PATH}"
+if [[ -x "$CORE_SCRIPT" ]]; then
+    exec "$CORE_SCRIPT" "$@"
+fi
+
+# Not found
+echo "Error: Script not found: $SCRIPT_PATH" >&2
+echo "" >&2
+echo "Searched:" >&2
+echo "  $PERSONAL_SCRIPT (personal)" >&2
+echo "  $CORE_SCRIPT (core)" >&2
+exit 1

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/collaboration/remembering-conversations/DEPLOYMENT.md

@@ -77,10 +77,10 @@ If issues found:
 ls -l ~/.claude/hooks/sessionEnd
 
 # Check recent conversations
-ls -lt ~/.clank/conversation-archive/*/*.jsonl | head -5
+ls -lt ~/.config/superpowers/conversation-archive/*/*.jsonl | head -5
 
 # Check database size
-ls -lh ~/.clank/conversation-index/db.sqlite
+ls -lh ~/.config/superpowers/conversation-index/db.sqlite
 
 # Full verification
 ./index-conversations --verify
@@ -190,14 +190,14 @@ sleep 60 && ./index-conversations --repair
 ./index-conversations --verify
 
 # 2. Check database exists and has data
-ls -lh ~/.clank/conversation-index/db.sqlite
+ls -lh ~/.config/superpowers/conversation-index/db.sqlite
 # Should be > 100KB if conversations indexed
 
 # 3. Try text search (exact match)
 ./search-conversations --text "exact phrase from conversation"
 
 # 4. Check for corruption
-sqlite3 ~/.clank/conversation-index/db.sqlite "SELECT COUNT(*) FROM exchanges;"
+sqlite3 ~/.config/superpowers/conversation-index/db.sqlite "SELECT COUNT(*) FROM exchanges;"
 # Should show number > 0
 ```
 
@@ -221,7 +221,7 @@ rm -rf ~/.cache/transformers  # Force re-download
 **Fix:**
 ```bash
 # 1. Backup current database
-cp ~/.clank/conversation-index/db.sqlite ~/.clank/conversation-index/db.sqlite.backup
+cp ~/.config/superpowers/conversation-index/db.sqlite ~/.config/superpowers/conversation-index/db.sqlite.backup
 
 # 2. Rebuild from scratch
 ./index-conversations --rebuild
@@ -300,7 +300,7 @@ cp ~/.clank/conversation-index/db.sqlite ~/.clank/conversation-index/db.sqlite.b
         └── prompts/
             └── search-agent.md    # Subagent template
 
-~/.clank/
+~/.config/superpowers/
 ├── conversation-archive/          # Archived conversations
 │   └── <project>/
 │       ├── <uuid>.jsonl          # Conversation file

skills/collaboration/remembering-conversations/INDEXING.md

@@ -25,7 +25,7 @@ Index, archive, and maintain conversations for search.
 - **Semantic search** across all past conversations
 - **AI summaries** (Claude Haiku with Sonnet fallback)
 - **Recovery modes** (verify, repair, rebuild)
-- **Permanent archive** at `~/.clank/conversation-archive/`
+- **Permanent archive** at `~/.config/superpowers/conversation-archive/`
 
 ## Setup
 
@@ -89,7 +89,7 @@ Handles existing hooks gracefully (merge or replace). Runs in background after e
 
 **Summaries failing:**
 - Check API key: `echo $ANTHROPIC_API_KEY`
-- Check logs in ~/.clank/conversation-index/
+- Check logs in ~/.config/superpowers/conversation-index/
 - Try manual: `./index-conversations --session <uuid>`
 
 **Search not finding results:**
@@ -101,7 +101,7 @@ Handles existing hooks gracefully (merge or replace). Runs in background after e
 
 To exclude specific projects from indexing (e.g., meta-conversations), create:
 
-`~/.clank/conversation-index/exclude.txt`
+`~/.config/superpowers/conversation-index/exclude.txt`
 ```
 # One project name per line
 # Lines starting with # are comments
@@ -115,10 +115,10 @@ export CONVERSATION_SEARCH_EXCLUDE_PROJECTS="project1,project2"
 
 ## Storage
 
-- **Archive:** `~/.clank/conversation-archive/<project>/<uuid>.jsonl`
-- **Summaries:** `~/.clank/conversation-archive/<project>/<uuid>-summary.txt`
-- **Database:** `~/.clank/conversation-index/db.sqlite`
-- **Exclusions:** `~/.clank/conversation-index/exclude.txt` (optional)
+- **Archive:** `~/.config/superpowers/conversation-archive/<project>/<uuid>.jsonl`
+- **Summaries:** `~/.config/superpowers/conversation-archive/<project>/<uuid>-summary.txt`
+- **Database:** `~/.config/superpowers/conversation-index/db.sqlite`
+- **Exclusions:** `~/.config/superpowers/conversation-index/exclude.txt` (optional)
 
 ## Technical Details
 

skills/collaboration/remembering-conversations/tool/index-conversations

@@ -22,6 +22,7 @@ COMMANDS:
 OPTIONS:
   --concurrency N    Parallel summarization (1-16, default: 1)
   -c N               Short form of --concurrency
+  --no-summaries     Skip AI summary generation (free, but no summaries in results)
   --help, -h         Show this help
 
 EXAMPLES:
@@ -31,6 +32,9 @@ EXAMPLES:
   # Index with 8 parallel summarizations (8x faster)
   index-conversations --cleanup --concurrency 8
 
+  # Index without AI summaries (free, fast)
+  index-conversations --cleanup --no-summaries
+
   # Check index health
   index-conversations --verify
 

skills/collaboration/remembering-conversations/tool/migrate-to-config.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# Migrate conversation archive and index from ~/.clank to ~/.config/superpowers
+#
+# IMPORTANT: This preserves all data. The old ~/.clank directory is not deleted,
+# allowing you to verify the migration before removing it manually.
+
+set -euo pipefail
+
+# Determine target directory
+SUPERPOWERS_DIR="${PERSONAL_SUPERPOWERS_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/superpowers}"
+
+OLD_ARCHIVE="$HOME/.clank/conversation-archive"
+OLD_INDEX="$HOME/.clank/conversation-index"
+
+NEW_ARCHIVE="${SUPERPOWERS_DIR}/conversation-archive"
+NEW_INDEX="${SUPERPOWERS_DIR}/conversation-index"
+
+echo "Migration: ~/.clank → ${SUPERPOWERS_DIR}"
+echo ""
+
+# Check if source exists
+if [[ ! -d "$HOME/.clank" ]]; then
+    echo "✅ No ~/.clank directory found. Nothing to migrate."
+    exit 0
+fi
+
+# Check if already migrated
+if [[ -d "$NEW_ARCHIVE" ]] || [[ -d "$NEW_INDEX" ]]; then
+    echo "⚠️  Destination already exists:"
+    [[ -d "$NEW_ARCHIVE" ]] && echo "  - ${NEW_ARCHIVE}"
+    [[ -d "$NEW_INDEX" ]] && echo "  - ${NEW_INDEX}"
+    echo ""
+    echo "Migration appears to have already run."
+    echo "To re-run migration, manually remove destination directories first."
+    exit 1
+fi
+
+# Show what will be migrated
+echo "Source directories:"
+if [[ -d "$OLD_ARCHIVE" ]]; then
+    archive_size=$(du -sh "$OLD_ARCHIVE" | cut -f1)
+    archive_count=$(find "$OLD_ARCHIVE" -name "*.jsonl" | wc -l | tr -d ' ')
+    echo "  Archive: ${OLD_ARCHIVE} (${archive_count} conversations, ${archive_size})"
+else
+    echo "  Archive: Not found"
+fi
+
+if [[ -d "$OLD_INDEX" ]]; then
+    index_size=$(du -sh "$OLD_INDEX" | cut -f1)
+    echo "  Index: ${OLD_INDEX} (${index_size})"
+else
+    echo "  Index: Not found"
+fi
+
+echo ""
+echo "Destination: ${SUPERPOWERS_DIR}"
+echo ""
+
+# Confirm
+read -p "Proceed with migration? [y/N] " -n 1 -r
+echo
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    echo "Migration cancelled."
+    exit 0
+fi
+
+# Ensure destination base exists
+mkdir -p "${SUPERPOWERS_DIR}"
+
+# Migrate archive
+if [[ -d "$OLD_ARCHIVE" ]]; then
+    echo "Copying conversation archive..."
+    cp -r "$OLD_ARCHIVE" "$NEW_ARCHIVE"
+    echo "  ✓ Archive migrated"
+fi
+
+# Migrate index
+if [[ -d "$OLD_INDEX" ]]; then
+    echo "Copying conversation index..."
+    cp -r "$OLD_INDEX" "$NEW_INDEX"
+    echo "  ✓ Index migrated"
+fi
+
+# Update database paths to point to new location
+if [[ -f "$NEW_INDEX/db.sqlite" ]]; then
+    echo "Updating database paths..."
+    sqlite3 "$NEW_INDEX/db.sqlite" "UPDATE exchanges SET archive_path = REPLACE(archive_path, '/.clank/', '/.config/superpowers/') WHERE archive_path LIKE '%/.clank/%';"
+    echo "  ✓ Database paths updated"
+fi
+
+# Verify migration
+echo ""
+echo "Verifying migration..."
+
+if [[ -d "$OLD_ARCHIVE" ]]; then
+    old_count=$(find "$OLD_ARCHIVE" -name "*.jsonl" | wc -l | tr -d ' ')
+    new_count=$(find "$NEW_ARCHIVE" -name "*.jsonl" | wc -l | tr -d ' ')
+
+    if [[ "$old_count" -eq "$new_count" ]]; then
+        echo "  ✓ All $new_count conversations migrated"
+    else
+        echo "  ⚠️  Conversation count mismatch: old=$old_count, new=$new_count"
+        exit 1
+    fi
+fi
+
+if [[ -f "$OLD_INDEX/db.sqlite" ]]; then
+    old_size=$(stat -f%z "$OLD_INDEX/db.sqlite" 2>/dev/null || stat --format=%s "$OLD_INDEX/db.sqlite" 2>/dev/null)
+    new_size=$(stat -f%z "$NEW_INDEX/db.sqlite" 2>/dev/null || stat --format=%s "$NEW_INDEX/db.sqlite" 2>/dev/null)
+    echo "  ✓ Database migrated (${new_size} bytes)"
+fi
+
+echo ""
+echo "✅ Migration complete!"
+echo ""
+echo "Next steps:"
+echo "  1. Test search: ./search-conversations 'test query'"
+echo "  2. Verify results look correct"
+echo "  3. Once verified, manually remove old directory:"
+echo "     rm -rf ~/.clank"
+echo ""
+echo "The old ~/.clank directory is preserved for safety."
+
+exit 0

skills/collaboration/remembering-conversations/tool/src/db.ts

@@ -1,13 +1,9 @@
 import Database from 'better-sqlite3';
 import { ConversationExchange } from './types.js';
 import path from 'path';
-import os from 'os';
 import fs from 'fs';
 import * as sqliteVec from 'sqlite-vec';
-
-function getDbPath(): string {
-  return process.env.TEST_DB_PATH || path.join(os.homedir(), '.clank', 'conversation-index', 'db.sqlite');
-}
+import { getDbPath } from './paths.js';
 
 export function migrateSchema(db: Database.Database): void {
   const hasColumn = db.prepare(`

skills/collaboration/remembering-conversations/tool/src/index-cli.ts

@@ -2,9 +2,9 @@
 import { verifyIndex, repairIndex } from './verify.js';
 import { indexSession, indexUnprocessed, indexConversations } from './indexer.js';
 import { initDatabase } from './db.js';
+import { getDbPath, getArchiveDir } from './paths.js';
 import fs from 'fs';
 import path from 'path';
-import os from 'os';
 
 const command = process.argv[2];
 
@@ -18,7 +18,13 @@ function getConcurrency(): number {
   return 1; // default
 }
 
+// Parse --no-summaries flag
+function getNoSummaries(): boolean {
+  return process.argv.includes('--no-summaries');
+}
+
 const concurrency = getConcurrency();
+const noSummaries = getNoSummaries();
 
 async function main() {
   try {
@@ -29,11 +35,11 @@ async function main() {
           console.error('Usage: index-cli index-session <session-id>');
           process.exit(1);
         }
-        await indexSession(sessionId, concurrency);
+        await indexSession(sessionId, concurrency, noSummaries);
         break;
 
       case 'index-cleanup':
-        await indexUnprocessed(concurrency);
+        await indexUnprocessed(concurrency, noSummaries);
         break;
 
       case 'verify':
@@ -74,14 +80,14 @@ async function main() {
         console.log('Rebuilding entire index...');
 
         // Delete database
-        const dbPath = path.join(os.homedir(), '.clank', 'conversation-index', 'db.sqlite');
+        const dbPath = getDbPath();
         if (fs.existsSync(dbPath)) {
           fs.unlinkSync(dbPath);
           console.log('Deleted existing database');
         }
 
         // Delete all summary files
-        const archiveDir = path.join(os.homedir(), '.clank', 'conversation-archive');
+        const archiveDir = getArchiveDir();
         if (fs.existsSync(archiveDir)) {
           const projects = fs.readdirSync(archiveDir);
           for (const project of projects) {
@@ -98,12 +104,12 @@ async function main() {
 
         // Re-index everything
         console.log('Re-indexing all conversations...');
-        await indexConversations(undefined, undefined, concurrency);
+        await indexConversations(undefined, undefined, concurrency, noSummaries);
         break;
 
       case 'index-all':
       default:
-        await indexConversations(undefined, undefined, concurrency);
+        await indexConversations(undefined, undefined, concurrency, noSummaries);
         break;
     }
   } catch (error) {

skills/collaboration/remembering-conversations/tool/src/indexer.ts

@@ -6,6 +6,7 @@ import { parseConversation } from './parser.js';
 import { initEmbeddings, generateExchangeEmbedding } from './embeddings.js';
 import { summarizeConversation } from './summarizer.js';
 import { ConversationExchange } from './types.js';
+import { getArchiveDir, getExcludeConfigPath } from './paths.js';
 
 // Set max output tokens for Claude SDK (used by summarizer)
 process.env.CLAUDE_CODE_MAX_OUTPUT_TOKENS = '20000';
@@ -19,10 +20,6 @@ function getProjectsDir(): string {
   return process.env.TEST_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects');
 }
 
-function getArchiveDir(): string {
-  return process.env.TEST_ARCHIVE_DIR || path.join(os.homedir(), '.clank', 'conversation-archive');
-}
-
 // Projects to exclude from indexing (configurable via env or config file)
 function getExcludedProjects(): string[] {
   // Check env variable first
@@ -31,7 +28,7 @@ function getExcludedProjects(): string[] {
   }
 
   // Check for config file
-  const configPath = path.join(os.homedir(), '.clank', 'conversation-index', 'exclude.txt');
+  const configPath = getExcludeConfigPath();
   if (fs.existsSync(configPath)) {
     const content = fs.readFileSync(configPath, 'utf-8');
     return content.split('\n').map(line => line.trim()).filter(line => line && !line.startsWith('#'));
@@ -61,7 +58,8 @@ async function processBatch<T, R>(
 export async function indexConversations(
   limitToProject?: string,
   maxConversations?: number,
-  concurrency: number = 1
+  concurrency: number = 1,
+  noSummaries: boolean = false
 ): Promise<void> {
   console.log('Initializing database...');
   const db = initDatabase();
@@ -69,9 +67,13 @@ export async function indexConversations(
   console.log('Loading embedding model...');
   await initEmbeddings();
 
+  if (noSummaries) {
+    console.log('⚠️  Running in no-summaries mode (skipping AI summaries)');
+  }
+
   console.log('Scanning for conversation files...');
   const PROJECTS_DIR = getProjectsDir();
-  const ARCHIVE_DIR = getArchiveDir();
+  const ARCHIVE_DIR = getArchiveDir(); // Now uses paths.ts
   const projects = fs.readdirSync(PROJECTS_DIR);
 
   let totalExchanges = 0;
@@ -142,24 +144,28 @@ export async function indexConversations(
       });
     }
 
-    // Batch summarize conversations in parallel
-    const needsSummary = toProcess.filter(c => !fs.existsSync(c.summaryPath));
-
-    if (needsSummary.length > 0) {
-      console.log(`  Generating ${needsSummary.length} summaries (concurrency: ${concurrency})...`);
-
-      await processBatch(needsSummary, async (conv) => {
-        try {
-          const summary = await summarizeConversation(conv.exchanges);
-          fs.writeFileSync(conv.summaryPath, summary, 'utf-8');
-          const wordCount = summary.split(/\s+/).length;
-          console.log(`  ✓ ${conv.file}: ${wordCount} words`);
-          return summary;
-        } catch (error) {
-          console.log(`  ✗ ${conv.file}: ${error}`);
-          return null;
-        }
-      }, concurrency);
+    // Batch summarize conversations in parallel (unless --no-summaries)
+    if (!noSummaries) {
+      const needsSummary = toProcess.filter(c => !fs.existsSync(c.summaryPath));
+
+      if (needsSummary.length > 0) {
+        console.log(`  Generating ${needsSummary.length} summaries (concurrency: ${concurrency})...`);
+
+        await processBatch(needsSummary, async (conv) => {
+          try {
+            const summary = await summarizeConversation(conv.exchanges);
+            fs.writeFileSync(conv.summaryPath, summary, 'utf-8');
+            const wordCount = summary.split(/\s+/).length;
+            console.log(`  ✓ ${conv.file}: ${wordCount} words`);
+            return summary;
+          } catch (error) {
+            console.log(`  ✗ ${conv.file}: ${error}`);
+            return null;
+          }
+        }, concurrency);
+      }
+    } else {
+      console.log(`  Skipping ${toProcess.length} summaries (--no-summaries mode)`);
     }
 
     // Now process embeddings and DB inserts (fast, sequential is fine)
@@ -190,12 +196,12 @@ export async function indexConversations(
   console.log(`\n✅ Indexing complete! Conversations: ${conversationsProcessed}, Exchanges: ${totalExchanges}`);
 }
 
-export async function indexSession(sessionId: string, concurrency: number = 1): Promise<void> {
+export async function indexSession(sessionId: string, concurrency: number = 1, noSummaries: boolean = false): Promise<void> {
   console.log(`Indexing session: ${sessionId}`);
 
   // Find the conversation file for this session
   const PROJECTS_DIR = getProjectsDir();
-  const ARCHIVE_DIR = getArchiveDir();
+  const ARCHIVE_DIR = getArchiveDir(); // Now uses paths.ts
   const projects = fs.readdirSync(PROJECTS_DIR);
   const excludedProjects = getExcludedProjects();
   let found = false;
@@ -230,9 +236,9 @@ export async function indexSession(sessionId: string, concurrency: number = 1):
       const exchanges = await parseConversation(sourcePath, project, archivePath);
 
       if (exchanges.length > 0) {
-        // Generate summary
+        // Generate summary (unless --no-summaries)
         const summaryPath = archivePath.replace('.jsonl', '-summary.txt');
-        if (!fs.existsSync(summaryPath)) {
+        if (!noSummaries && !fs.existsSync(summaryPath)) {
           const summary = await summarizeConversation(exchanges);
           fs.writeFileSync(summaryPath, summary, 'utf-8');
           console.log(`Summary: ${summary.split(/\s+/).length} words`);
@@ -260,15 +266,16 @@ export async function indexSession(sessionId: string, concurrency: number = 1):
   }
 }
 
-export async function indexUnprocessed(concurrency: number = 1): Promise<void> {
+export async function indexUnprocessed(concurrency: number = 1, noSummaries: boolean = false): Promise<void> {
   console.log('Finding unprocessed conversations...');
   if (concurrency > 1) console.log(`Concurrency: ${concurrency}`);
+  if (noSummaries) console.log('⚠️  Running in no-summaries mode (skipping AI summaries)');
 
   const db = initDatabase();
   await initEmbeddings();
 
   const PROJECTS_DIR = getProjectsDir();
-  const ARCHIVE_DIR = getArchiveDir();
+  const ARCHIVE_DIR = getArchiveDir(); // Now uses paths.ts
   const projects = fs.readdirSync(PROJECTS_DIR);
   const excludedProjects = getExcludedProjects();
 
@@ -298,8 +305,11 @@ export async function indexUnprocessed(concurrency: number = 1): Promise<void> {
       const archivePath = path.join(projectArchive, file);
       const summaryPath = archivePath.replace('.jsonl', '-summary.txt');
 
-      // Skip if already has summary
-      if (fs.existsSync(summaryPath)) continue;
+      // Check if already indexed in database
+      const alreadyIndexed = db.prepare('SELECT COUNT(*) as count FROM exchanges WHERE archive_path = ?')
+        .get(archivePath) as { count: number };
+
+      if (alreadyIndexed.count > 0) continue;
 
       fs.mkdirSync(projectArchive, { recursive: true });
 
@@ -323,21 +333,29 @@ export async function indexUnprocessed(concurrency: number = 1): Promise<void> {
   }
 
   console.log(`Found ${unprocessed.length} unprocessed conversations`);
-  console.log(`Generating summaries (concurrency: ${concurrency})...\n`);
-
-  // Batch process summaries
-  await processBatch(unprocessed, async (conv) => {
-    try {
-      const summary = await summarizeConversation(conv.exchanges);
-      fs.writeFileSync(conv.summaryPath, summary, 'utf-8');
-      const wordCount = summary.split(/\s+/).length;
-      console.log(`  ✓ ${conv.project}/${conv.file}: ${wordCount} words`);
-      return summary;
-    } catch (error) {
-      console.log(`  ✗ ${conv.project}/${conv.file}: ${error}`);
-      return null;
+
+  // Batch process summaries (unless --no-summaries)
+  if (!noSummaries) {
+    const needsSummary = unprocessed.filter(c => !fs.existsSync(c.summaryPath));
+    if (needsSummary.length > 0) {
+      console.log(`Generating ${needsSummary.length} summaries (concurrency: ${concurrency})...\n`);
+
+      await processBatch(needsSummary, async (conv) => {
+        try {
+          const summary = await summarizeConversation(conv.exchanges);
+          fs.writeFileSync(conv.summaryPath, summary, 'utf-8');
+          const wordCount = summary.split(/\s+/).length;
+          console.log(`  ✓ ${conv.project}/${conv.file}: ${wordCount} words`);
+          return summary;
+        } catch (error) {
+          console.log(`  ✗ ${conv.project}/${conv.file}: ${error}`);
+          return null;
+        }
+      }, concurrency);
     }
-  }, concurrency);
+  } else {
+    console.log(`Skipping summaries for ${unprocessed.length} conversations (--no-summaries mode)\n`);
+  }
 
   // Now index embeddings
   console.log(`\nIndexing embeddings...`);

skills/collaboration/remembering-conversations/tool/src/paths.ts

@@ -0,0 +1,56 @@
+import os from 'os';
+import path from 'path';
+
+/**
+ * Get the personal superpowers directory
+ *
+ * Precedence:
+ * 1. PERSONAL_SUPERPOWERS_DIR env var (if set)
+ * 2. XDG_CONFIG_HOME/superpowers (if XDG_CONFIG_HOME is set)
+ * 3. ~/.config/superpowers (default)
+ */
+export function getSuperpowersDir(): string {
+  if (process.env.PERSONAL_SUPERPOWERS_DIR) {
+    return process.env.PERSONAL_SUPERPOWERS_DIR;
+  }
+
+  const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+  if (xdgConfigHome) {
+    return path.join(xdgConfigHome, 'superpowers');
+  }
+
+  return path.join(os.homedir(), '.config', 'superpowers');
+}
+
+/**
+ * Get conversation archive directory
+ */
+export function getArchiveDir(): string {
+  // Allow test override
+  if (process.env.TEST_ARCHIVE_DIR) {
+    return process.env.TEST_ARCHIVE_DIR;
+  }
+
+  return path.join(getSuperpowersDir(), 'conversation-archive');
+}
+
+/**
+ * Get conversation index directory
+ */
+export function getIndexDir(): string {
+  return path.join(getSuperpowersDir(), 'conversation-index');
+}
+
+/**
+ * Get database path
+ */
+export function getDbPath(): string {
+  return path.join(getIndexDir(), 'db.sqlite');
+}
+
+/**
+ * Get exclude config path
+ */
+export function getExcludeConfigPath(): string {
+  return path.join(getIndexDir(), 'exclude.txt');
+}

skills/collaboration/remembering-conversations/tool/src/verify.ts

@@ -1,8 +1,8 @@
 import fs from 'fs';
 import path from 'path';
-import os from 'os';
 import { parseConversation } from './parser.js';
 import { initDatabase, getAllExchanges, getFileLastIndexed } from './db.js';
+import { getArchiveDir } from './paths.js';
 
 export interface VerificationResult {
   missing: Array<{ path: string; reason: string }>;
@@ -11,11 +11,6 @@ export interface VerificationResult {
   corrupted: Array<{ path: string; error: string }>;
 }
 
-// Allow overriding paths for testing
-function getArchiveDir(): string {
-  return process.env.TEST_ARCHIVE_DIR || path.join(os.homedir(), '.clank', 'conversation-archive');
-}
-
 export async function verifyIndex(): Promise<VerificationResult> {
   const result: VerificationResult = {
     missing: [],

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,19 +1,32 @@
 ---
 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?
 
-**RIGHT NOW**: Run this to see what skills are available:
+**RIGHT NOW**: Find the plugin location and list skills:
+```bash
+# Find plugin location
+find ~/.claude/plugins/cache -name "superpowers" -type d 2>/dev/null | grep -v ".git" | head -1
+
+# Then run (replace PATH with the path found above):
+PATH/scripts/find-skills
+```
+
+Or just use the full path directly:
 ```bash
-${CLAUDE_PLUGIN_ROOT}/skills/getting-started/list-skills
+~/.claude/plugins/cache/superpowers/scripts/find-skills
 ```
 
 **THEN**: Follow the workflows below based on what your partner is asking for.
@@ -28,7 +41,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
@@ -46,21 +60,19 @@ ${CLAUDE_PLUGIN_ROOT}/skills/getting-started/list-skills
 
 ## Mandatory Workflow 2: Before ANY Task
 
-**1. List available skills** (to avoid useless searches):
-```bash
-${CLAUDE_PLUGIN_ROOT}/skills/getting-started/list-skills
-```
+**1. Find skills** (shows all, or filter by pattern):
 
-**2. Search skills** (when you need something specific):
+Use the plugin cache path (default: `~/.claude/plugins/cache/superpowers`):
 ```bash
-${CLAUDE_PLUGIN_ROOT}/skills/getting-started/skills-search PATTERN
+~/.claude/plugins/cache/superpowers/scripts/find-skills           # Show all
+~/.claude/plugins/cache/superpowers/scripts/find-skills PATTERN   # Filter by pattern
 ```
 
-**3. Search conversations:**
+**2. Search conversations:**
 Dispatch subagent (see Workflow 3) to check for relevant past work.
 
 **If skills found:**
-1. READ the skill: `${CLAUDE_PLUGIN_ROOT}/skills/path/skill-name/SKILL.md`
+1. READ the skill - check personal first (`~/.config/superpowers/skills/path/SKILL.md`), then core (`~/.claude/plugins/cache/superpowers/skills/path/SKILL.md`)
 2. ANNOUNCE usage: "I'm using the [Skill Name] skill"
 3. FOLLOW the skill (many are rigid requirements)
 
@@ -115,14 +127,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 +164,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,17 +180,20 @@ 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
 
 **Starting conversation?** You just read this. Good.
 
-**Starting any task?** Run skills-search first, announce usage, follow what you find.
+**Starting any task?** Run find-skills first, announce usage, follow what you find.
 
 **Skill has checklist?** TodoWrite for every item.
 

skills/getting-started/list-skills

@@ -1,22 +0,0 @@
-#!/usr/bin/env bash
-# list-skills - Show all available skill names without descriptions
-# For Claude to quickly see what exists before searching
-
-set -euo pipefail
-
-# Detect if running from 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)"
-else
-    # Running from repo
-    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
-
-exit 0

skills/getting-started/skills-search

@@ -1,83 +0,0 @@
-#!/usr/bin/env bash
-# skills-search - Find relevant skills using grep patterns
-# Logs all searches for gap analysis (gardening skill processes the log)
-
-set -euo pipefail
-
-# Detect if running from 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"
-else
-    # Running from repo
-    SKILLS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
-fi
-
-LOG_FILE="${HOME}/.superpowers/search-log.jsonl"
-
-# Show usage if no arguments
-if [[ $# -eq 0 ]]; then
-    cat <<'EOF'
-Usage: skills-search PATTERN [PATTERN...]
-
-Searches skills using grep patterns.
-
-Examples:
-  skills-search 'test.*driven|TDD'
-  skills-search 'debug.*systematic|root.cause'
-  skills-search 'refactor|extract'
-  skills-search 'async.*test|flaky|timeout'
-  skills-search 'validat.*input'
-
-The search is logged. Failed searches help identify missing skills.
-EOF
-    exit 1
-fi
-
-# Log the search for gap analysis
-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)
-
-# 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)
-
-# Combine and deduplicate
-results=$(printf "%s\n%s" "$content_matches" "$path_matches" | sort -u | grep -v '^$' || true)
-
-if [[ -z "$results" ]]; then
-    echo "❌ No skills found matching: $*"
-    echo ""
-    echo "Search logged. If a skill should exist, it will be created."
-    echo "Proceed carefully - document your approach."
-    exit 0
-fi
-
-echo "✅ Found skills:"
-echo ""
-
-# Display results with metadata
-echo "$results" | while read -r file; do
-    # Extract description from frontmatter
-    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/}"
-    rel_path="skills/${rel_path%/SKILL.md}"
-
-    if [[ -n "$description" ]]; then
-        echo "$rel_path - $description"
-    else
-        echo "$rel_path"
-    fi
-done
-
-echo ""
-
-exit 0

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 `find-skills` tool automatically searches 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}/scripts/find-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"
 
@@ -568,12 +571,17 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 - [ ] No narrative storytelling
 - [ ] Supporting files only for tools or heavy reference
 
+**Deployment:**
+- [ ] Commit skill to git (in `~/.config/superpowers/`)
+- [ ] Push to GitHub (if remote configured)
+- [ ] Consider sharing via skills/meta/sharing-skills (if broadly useful)
+
 ## Discovery Workflow
 
 How future Claude finds your skill:
 
 1. **Encounters problem** ("tests are flaky")
-2. **Greps skills** (`grep -r "flaky" ~/.claude/skills/`)
+2. **Searches skills** using `find-skills` 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.