This page documents the layout of the obra/superpowers repository and describes what lives in each directory. It covers the plugin integration files, the skills library layout, shared code modules, test infrastructure, and documentation. For information about how individual configuration files work, see Configuration Files. For the hooks system specifically, see Hooks System. For how the skills repository itself is managed as a separate concern, see Dual Repository Design.
The root of the repository is organized around platform-specific plugin directories (prefixed with .), shared runtime directories, and developer tooling.
Top-level directory structure
Sources: .cursor-plugin/plugin.json14-17 README.md1-153
These directories contain content that is loaded at runtime by the platform integrations.
skills/The primary skill library. Each subdirectory is a named skill containing a SKILL.md file with YAML frontmatter and Markdown content. The directory is scanned recursively by findSkillsInDir in lib/skills-core.js.
Example layout within skills/:
skills/
├── brainstorming/
│ └── SKILL.md
├── test-driven-development/
│ └── SKILL.md
├── systematic-debugging/
│ └── SKILL.md
├── using-superpowers/
│ └── SKILL.md
├── writing-plans/
│ └── SKILL.md
├── subagent-driven-development/
│ └── SKILL.md
├── executing-plans/
│ └── SKILL.md
├── requesting-code-review/
│ └── SKILL.md
├── receiving-code-review/
│ └── SKILL.md
├── using-git-worktrees/
│ └── SKILL.md
├── finishing-a-development-branch/
│ └── SKILL.md
├── dispatching-parallel-agents/
│ └── SKILL.md
├── verification-before-completion/
│ └── SKILL.md
└── writing-skills/
└── SKILL.md
For information on the SKILL.md format, see SKILL.md Format and Structure. For how skills are discovered at runtime, see Skills Discovery and Resolution.
Sources: README.md98-121 .cursor-plugin/plugin.json14
agents/Definitions for named subagents dispatched during workflows such as subagent-driven-development. Referenced by .cursor-plugin/plugin.json as "agents": "./agents/".
Sources: .cursor-plugin/plugin.json15
commands/Slash-command definitions for Claude Code. Contains Markdown files such as brainstorm.md, write-plan.md, and execute-plan.md. Commands use disable-model-invocation: true to delegate execution to the corresponding skill. See Command Definitions for full documentation.
Sources: .cursor-plugin/plugin.json16
hooks/Contains hooks.json, which configures the SessionStart lifecycle hook for Claude Code and Cursor. The hooks directory also contains the session-start shell script executed at the start of each session. See Hooks System for details.
Sources: .cursor-plugin/plugin.json17
lib/Shared JavaScript modules. The primary module is lib/skills-core.js, which exports the following functions used by the OpenCode plugin:
| Function | Purpose |
|---|---|
extractFrontmatter | Parses YAML frontmatter from a SKILL.md string |
stripFrontmatter | Removes the frontmatter block, returning only Markdown content |
findSkillsInDir | Recursively scans a directory for SKILL.md files |
resolveSkillPath | Resolves a skill name to an absolute file path |
checkForUpdates | Checks the git remote for available updates |
See skills-core.js Shared Module for full API documentation.
Sources: README.md1-153
Each supported platform has its own configuration directory at the repo root. These directories contain platform-specific manifests, install instructions, and plugin entry points.
Platform directory to integration mapping
Sources: .cursor-plugin/plugin.json1-18 README.md32-72
.claude-plugin/Files consumed by the Claude Code plugin marketplace. Key files:
| File | Purpose |
|---|---|
plugin.json | Plugin manifest: name, version, skills path, hooks path |
marketplace.json | Marketplace registration metadata |
run-hook.cmd | Polyglot wrapper executable (Windows CMD + Unix bash in one file) |
See Claude Code Integration and Configuration Files for field-level documentation.
.cursor-plugin/Files consumed by the Cursor plugin system.
| File | Purpose |
|---|---|
plugin.json | Manifest declaring skills, agents, commands, and hooks paths |
The plugin.json references all four runtime directories: ./skills/, ./agents/, ./commands/, and ./hooks/hooks.json. See .cursor-plugin/plugin.json1-18
.opencode/Files for the OpenCode integration.
| File | Purpose |
|---|---|
INSTALL.md | Instructions fetched and executed by the agent during manual install |
superpowers.js | OpenCode plugin entry point; registers the experimental.chat.system.transform hook |
See OpenCode Integration for the plugin internals.
.codex/Files for the OpenAI Codex CLI integration.
| File | Purpose |
|---|---|
INSTALL.md | Instructions fetched and executed by the agent during manual install |
Codex uses native skill discovery at ~/.agents/skills/, so no plugin entry point is needed. See Codex Integration for the install lifecycle.
The tests/ directory contains separate test suites organized by platform and test type.
Test directory structure
| Script | Purpose |
|---|---|
run-skill-tests.sh | Runs Claude Code fast and integration tests; supports --verbose, --test, --timeout, --integration |
test-helpers.sh | Provides run_claude, assert_contains, assert_order, assert_not_contains helpers |
run-tests.sh | OpenCode test orchestrator |
setup.sh | Creates an isolated environment for OpenCode tests via TEST_HOME |
test-skills-core.sh | Unit tests for lib/skills-core.js functions |
test-priority.sh | Integration tests for the three-tier skill priority system |
test-tools.sh | Validates tool mapping between platforms |
test-plugin-loading.sh | Verifies plugin loads correctly in OpenCode |
analyze-token-usage.py | Parses .jsonl session files to extract per-subagent token counts and costs |
See Claude Code Test Suite, OpenCode Test Suite, and Integration Test Cases for detailed documentation.
Sources: README.md1-153
The docs/ directory holds human-readable documentation and plan files.
| Path | Purpose |
|---|---|
docs/README.codex.md | Detailed Codex installation and usage guide |
docs/README.opencode.md | Detailed OpenCode installation and usage guide |
docs/plans/ | Implementation plan files created by the writing-plans skill; named by feature |
The docs/plans/ subdirectory follows the naming convention described in Writing Implementation Plans.
Sources: README.md62-72
The .gitignore excludes several directories that may exist at runtime but are not committed:
| Path | Reason Excluded |
|---|---|
.worktrees/ | Git worktrees created by the using-git-worktrees skill |
.private-journal/ | Agent private notes; not shared |
.claude/ | Claude Code local settings and session data |
Sources: .gitignore1-4
| Directory | Role | Used By |
|---|---|---|
skills/ | Skill SKILL.md library | All platforms |
agents/ | Subagent definitions | Claude Code, Cursor |
commands/ | Slash-command Markdown files | Claude Code, Cursor |
hooks/ | hooks.json and session-start script | Claude Code, Cursor |
lib/ | skills-core.js shared module | OpenCode plugin |
.claude-plugin/ | Claude Code manifest, marketplace, hook runner | Claude Code |
.cursor-plugin/ | Cursor manifest | Cursor |
.opencode/ | OpenCode plugin entry point and install script | OpenCode |
.codex/ | Codex install script | Codex |
tests/ | All test suites | Development/CI |
docs/ | Human docs, plan files | All |
Sources: .cursor-plugin/plugin.json1-18 README.md1-153 .gitignore1-4
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.