Skip to content

An agentic skills framework & software development methodology that works.

Update README to reflect new skills repository architecture

Jesse Vincenta1a1c3119d55
diff --git a/README.md b/README.md
index 1fe6c0701..c49346b4b 100644
--- a/README.md
+++ b/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