This page explains the architectural relationship between the obra/superpowers plugin repository and the separate obra/superpowers-skills skills library, covering why they were separated at v2.0.0, how independent versioning was intended to work, and the current consolidated state of the codebase. For details on how each platform integrates with this structure at runtime, see Multi-Platform Integration (4.3). For how skill files are discovered and resolved on disk, see Skills Discovery and Resolution (4.5).
The superpowers project spans up to three separate Git repositories depending on the version and platform:
| Repository | Purpose | Used by |
|---|---|---|
obra/superpowers | Plugin integrations, hooks, agents, commands, skills library | All platforms |
obra/superpowers-skills | Standalone skills library (v2.0.0 era) | Historical only |
obra/superpowers-marketplace | Claude Code plugin marketplace registration | Claude Code, Cursor |
The plugin manifest in .claude-plugin/plugin.json and .cursor-plugin/plugin.json both point to the obra/superpowers repository as their "homepage" and "repository".
Sources: .claude-plugin/plugin.json .cursor-plugin/plugin.json README.md
Diagram: Repository Architecture Across Versions
Sources: RELEASE-NOTES.md572-601 RELEASE-NOTES.md550-556 README.md130-144
Version 2.0.0 introduced the headline change described in RELEASE-NOTES.md572-601:
Skills no longer live in the plugin. They've been moved to a separate repository at
obra/superpowers-skills.
The motivation was:
lib/initialize-skills.sh was the bridge between the two repositories. On first run it:
obra/superpowers-skills to ~/.config/superpowers/skills/gh was installed) so users could contribute backupstream/origin remotes for the standard fork-and-PR workflowThe environment variable SUPERPOWERS_SKILLS_ROOT was set to ~/.config/superpowers/skills and used consistently throughout hooks and commands.
Diagram: v2.0.0 Session-Start Clone Mechanism
Sources: RELEASE-NOTES.md612-640 RELEASE-NOTES.md686-729
As of v3.0.1 (RELEASE-NOTES.md550-556), the project switched to Anthropic's first-party Claude Code skills and plugin system. This eliminated the need for a separate skills repository clone mechanism. The skills/ directory now lives directly inside obra/superpowers.
Diagram: Current obra/superpowers Repository Layout
Sources: .cursor-plugin/plugin.json14-17 README.md131-140 RELEASE-NOTES.md3
The .cursor-plugin/plugin.json manifest at .cursor-plugin/plugin.json14-17 explicitly references local paths:
All four content directories are relative to the plugin root. Platforms load them directly from the installed plugin, with no external clone step required. This means:
/plugin update superpowers updates both platform integration code and skills in a single operationgit fetchobra/superpowers, not a separate repoThe lib/skills-core.js shared module (used by OpenCode and historically by Codex) handles all skill file discovery against whichever local path the platform provides. See skills-core.js Shared Module (5.4) for its API.
Sources: .cursor-plugin/plugin.json1-18 README.md131-141 RELEASE-NOTES.md339-346
The obra/superpowers-marketplace repository remains separate. It is a plugin registry, not a skills library. Its only role is to allow Claude Code and Cursor to discover and install the obra/superpowers plugin.
The local development version of the marketplace manifest lives at .claude-plugin/marketplace.json and points "source": "./", meaning the local checkout acts as its own marketplace entry during development and testing.
For production installs, the workflow is:
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
The marketplace and the plugin version their manifests independently: bumping the plugin's "version" field in .claude-plugin/plugin.json4 does not require a change to the marketplace registry.
Sources: .claude-plugin/marketplace.json1-20 .claude-plugin/plugin.json1-13 README.md34-39
| Component | Versioned Where | Updated How |
|---|---|---|
| Plugin integrations (hooks, manifest) | obra/superpowers version field | /plugin update superpowers |
| Skills content | obra/superpowers skills/ directory | Same plugin update |
| Marketplace registry | obra/superpowers-marketplace | Separate PR to marketplace repo |
Shared lib (skills-core.js) | obra/superpowers lib/ | Same plugin update |
The historical v2.0.0 era had skills versioned separately in obra/superpowers-skills with independent git history. That design was replaced when the project adopted Claude Code's native plugin model.
Sources: RELEASE-NOTES.md572-601 RELEASE-NOTES.md550-556 .claude-plugin/plugin.json3
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.