This page documents the layout of the obra/superpowers repository and describes the purpose of each directory. It covers platform integration files, the skills library layout, and development configuration as of version 6.1.1.
The root of the repository is organized around platform-specific plugin directories (prefixed with .), the core skills library, and development configuration. The repository uses a multi-platform architecture where a single set of skills is exposed to various AI agents through platform-specific manifests.
Top-level directory structure
Sources: .gitignore1-8 README.md1-184 .claude-plugin/marketplace.json1-20 .codex-plugin/plugin.json1-48
The skills/ directory is the heart of the Superpowers system. It contains the modular units of AI guidance that define the development methodology.
skills/Each subdirectory within skills/ represents a specific capability (e.g., brainstorming, test-driven-development). Every skill directory contains a SKILL.md file which acts as the entry point for the AI agent.
Skill Definition Mapping
SKILL.md: Contains instructions for the AI agent to execute specific workflows like brainstorming or writing-plans README.md190-194skills field in their manifest to point to this directory for automatic discovery .codex-plugin/plugin.json23using-superpowers skill acts as the root of the hierarchy, enforcing the "1% rule" and providing the basic workflow instructions README.md186-187Sources: README.md188-204 .codex-plugin/plugin.json23
Superpowers integrates with multiple AI platforms using specific configuration files located at the root or in hidden directories.
Platform Entry Point Mapping
.claude-plugin/Contains configuration for the Claude Code marketplace integration. The marketplace.json defines the plugin name, version (6.1.1), and source location .claude-plugin/marketplace.json1-20
.codex-plugin/Contains the manifest for Codex App and Codex CLI. It defines capabilities (Interactive, Read, Write), brand assets, and points to the skills/ directory .codex-plugin/plugin.json1-48 It explicitly declares an empty hooks object to suppress default hook auto-discovery in favor of Superpowers' custom logic tests/codex/test-marketplace-manifest.sh69-73
.agents/plugins/Used for development and testing of marketplace manifests. The marketplace.json here defines a "Superpowers Dev" entry used during integration testing .agents/plugins/marketplace.json1-20
hooks/Contains scripts for session initialization. For example, hooks/hooks.json tracks the Claude Code SessionStart hook tests/codex/test-marketplace-manifest.sh65-67
Sources: README.md36-157 .claude-plugin/marketplace.json1-20 .codex-plugin/plugin.json1-48 tests/codex/test-marketplace-manifest.sh1-76
The repository includes standard configuration files to manage the development environment and ensure workflow isolation.
.gitignoreThe ignore file is specifically configured to support the using-git-worktrees skill, which requires isolated environments for development branches.
| Pattern | Purpose |
|---|---|
.worktrees/ | Stores isolated git worktrees used by the using-git-worktrees skill .gitignore1 |
.private-journal/ | Local notes and logs not intended for version control .gitignore2 |
.claude/ | Local configuration and session data for Claude Code .gitignore3 |
node_modules/ | Standard Node.js dependency directory .gitignore6 |
evals/ | Ignored directory for the evaluation harness repository .gitignore13 |
Sources: .gitignore1-14 README.md192
| Directory/File | Role | Key Files |
|---|---|---|
skills/ | The core library of AI development workflows. | SKILL.md |
.claude-plugin/ | Claude Code marketplace and plugin configuration. | marketplace.json |
.codex-plugin/ | Codex-specific manifest and capabilities. | plugin.json |
hooks/ | Scripts for session initialization and lifecycle management. | hooks.json |
tests/ | Automated validation of skills and platform integrations. | test-marketplace-manifest.sh |
.agents/ | Internal agent/marketplace testing configurations. | plugins/marketplace.json |
.gitignore | Manages environment isolation (especially for worktrees). | .gitignore |
Sources: README.md1-204 .gitignore1-14 .codex-plugin/plugin.json1-48 .claude-plugin/marketplace.json1-20