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.mdindex 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-## LicenseMIT License - see LICENSE file for details