Update README to reflect new skills repository architecture

README.md

@@ -2,6 +2,15 @@
 
 Give Claude Code superpowers with a comprehensive skills library of proven techniques, patterns, and tools.
 
+## Architecture
+
+The superpowers plugin is a minimal shim that:
+- Clones/updates the [superpowers-skills](https://github.com/obra/superpowers-skills) repository to `~/.config/superpowers/skills/`
+- Registers hooks that load skills from the local repository
+- Offers users the option to fork the skills repo for contributions
+
+All skills, scripts, and documentation live in the separate superpowers-skills repository. Users can edit skills locally, commit changes, and optionally contribute back via pull requests.
+
 ## What You Get
 
 - **Testing Skills** - TDD, async testing, anti-patterns
@@ -28,12 +37,7 @@ Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/
 /plugin install superpowers@superpowers-marketplace
 ```
 
-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
+The plugin automatically handles skills repository setup on first run.
 
 ### Verify Installation
 
@@ -47,27 +51,29 @@ That's it! On first session, the plugin automatically:
 # /execute-plan - Execute plan in batches
 ```
 
-## Quick Start
+## Updating Skills
+
+The plugin checks for upstream skill updates on each session start. To update your local skills, ask Claude to use the updating-skills skill when notified of new upstream changes.
+
+## Contributing Skills
 
-### Your Personal Skills
+If you forked the skills repository during setup, you can contribute improvements:
 
-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
+1. Edit skills in `~/.config/superpowers/skills/`
+2. Commit your changes
+3. Push to your fork
+4. Open a PR to `obra/superpowers-skills`
 
-See `skills/meta/writing-skills` for how to create new skills.
-See `skills/meta/sharing-skills` for how to contribute to core.
+## Quick Start
 
 ### Finding Skills
 
-Find both personal and core skills before starting any task:
+Find skills before starting any task:
 
 ```bash
-${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
+${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills              # All skills with descriptions
+${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills test         # Filter by pattern
+${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills 'TDD|debug'  # Regex pattern
 ```
 
 ### Using Slash Commands
@@ -127,28 +133,23 @@ ${CLAUDE_PLUGIN_ROOT}/scripts/find-skills 'TDD|debug'  # Regex pattern
 
 ### Tools
 
-**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:**
+- **find-skills** - Unified skill discovery with descriptions
+- **skill-run** - Generic runner for any skill script
 - **search-conversations** - Semantic search of past Claude sessions (in remembering-conversations skill)
 
-**Using scripts:**
+**Using tools:**
 ```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
+${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills              # Show all skills
+${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills pattern      # Search skills
+${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/skill-run <path> [args]  # Run any skill script
 ```
 
 ## How It Works
 
-1. **SessionStart Hook** - 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`
+1. **SessionStart Hook** - Clone/update skills repo, inject skills context
+2. **Skills Discovery** - `find-skills` shows all available skills with descriptions
+3. **Mandatory Workflow** - Skills become required when they exist for your task
+4. **Gap Tracking** - Failed searches logged for skill development
 
 ## Philosophy
 
@@ -158,50 +159,6 @@ ${CLAUDE_PLUGIN_ROOT}/scripts/skill-run <path> [args]     # Run any skill script
 - **Evidence over claims** - Verify before declaring success
 - **Domain over implementation** - Work at problem level, not solution level
 
-## Personal Superpowers Directory
-
-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
-```
-
-**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
-
-**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
-
 ## License
 
 MIT License - see LICENSE file for details