Skip to main content

​
System Architecture

Superpowers is a modular system built around composable skills, hooks, plugins, commands, and agents that work together to provide a complete development workflow.

​
Core Components

Skills

Reusable workflow modules that guide agents through specific tasks like TDD, debugging, and brainstorming.

Hooks

Lifecycle event handlers that inject context at specific points, like session start.

Plugins

Platform-specific packages that register Superpowers with different AI coding tools.

Commands

Slash commands that invoke skills directly (e.g., /brainstorm).

Agents

Specialized subagents for specific tasks like code review.

Skills Core

Core library for skill discovery, resolution, and loading.

​
How Components Fit Together

​
Directory Structure

Superpowers follows a consistent structure across all platforms: 
superpowers/
├── .claude-plugin/           # Claude Code plugin manifest
│   ├── plugin.json          # Package metadata + paths
│   └── marketplace.json     # Marketplace configuration
├── .cursor-plugin/           # Cursor plugin manifest
│   └── plugin.json          # Package metadata + paths
├── .codex/                   # Codex installation instructions
│   └── INSTALL.md
├── .opencode/                # OpenCode plugin + instructions
│   ├── INSTALL.md
│   └── plugins/
│       └── superpowers.js   # OpenCode plugin implementation
├── skills/                   # Skills library
│   ├── brainstorming/
│   │   └── SKILL.md         # Skill definition with frontmatter
│   ├── test-driven-development/
│   ├── systematic-debugging/
│   └── .../
├── hooks/                    # Hooks configuration + scripts
│   ├── hooks.json           # Hook definitions
│   ├── run-hook.cmd         # Cross-platform wrapper
│   └── session-start        # SessionStart hook script
├── commands/                 # Slash commands
│   ├── brainstorm.md        # /brainstorm command
│   ├── write-plan.md        # /write-plan command
│   └── execute-plan.md      # /execute-plan command
├── agents/                   # Specialized subagents
│   └── code-reviewer.md     # Code review agent
├── lib/                      # Core libraries
│   └── skills-core.js       # Skills discovery & resolution
└── docs/                     # Documentation
    ├── README.codex.md
    ├── README.opencode.md
    └── plans/

​
Skills System

​
Skill Discovery

The skills system uses lib/skills-core.js to discover and resolve skills from multiple sources:
1

Find SKILL.md Files

Recursively searches configured directories for SKILL.md files (up to 3 levels deep):
// From lib/skills-core.js:62
function findSkillsInDir(dir, sourceType, maxDepth = 3) {
  const skills = [];
  // Recursively finds all SKILL.md files
  // Extracts frontmatter (name, description)
  // Returns array of skill metadata
}
2

Extract Frontmatter

Each skill has YAML frontmatter with metadata:
---
name: brainstorming
description: Use when creating features - explores requirements before implementation
---

# Brainstorming Ideas Into Designs
[skill content...]
The extractFrontmatter() function parses this to get the skill’s name and description.
3

Skill Resolution with Shadowing

Skills are resolved with priority order (personal > superpowers):
// From lib/skills-core.js:108
function resolveSkillPath(skillName, superpowersDir, personalDir) {
  // 1. Try personal skills first (unless superpowers: prefix)
  // 2. Fall back to superpowers skills
  // 3. Return skill file path + metadata
}
This allows users to override superpowers skills with their own versions.

​
Skill Invocation Flow

​
Plugin Architecture

​
Platform Differences

These platforms have built-in plugin marketplaces and automatic installation:
  • Registration: Via plugin marketplace commands
  • Distribution: Git repository URLs
  • Updates: Automatic via /plugin update
  • Hooks: Automatically registered from hooks.json
  • Skills: Automatically discovered from skills/ directory
OpenCode uses a hybrid approach with manual setup + plugin code:
  • Registration: Manual symlink to ~/.config/opencode/plugins/superpowers.js
  • Distribution: Manual git clone
  • Updates: Manual git pull
  • Skills: Manual symlink to ~/.config/opencode/skills/superpowers
  • Bootstrap: Plugin injects context via system prompt transform
See Plugin System for implementation details.

​
Commands System

Commands are simple wrappers that invoke skills directly: 
---
description: "Use before creative work - explores requirements and design"
disable-model-invocation: true
---

Invoke the superpowers:brainstorming skill and follow it exactly
Commands provide:
  • Convenience: /brainstorm instead of manually invoking skill tool
  • Discoverability: Listed in platform command menus
  • Consistency: Same interface across platforms

​
Agents System

Agents are specialized subagents with specific roles: 
---
name: code-reviewer
description: Reviews completed work against plan and coding standards
model: inherit
---

# Agent instructions...
Key features:
  • Isolated context: Fresh agent per invocation
  • Specialized knowledge: Role-specific instructions
  • Model inheritance: Uses same model as parent
  • Structured output: Consistent review format

​
Hook System Integration

Hooks integrate with platform lifecycle events. See Hooks System for details.

​
Key Design Principles

Modularity: Each component (skill, hook, command, agent) is independent and composable.
Platform Abstraction: Core skills work across all platforms; only installation differs.
User Override: Personal skills always shadow superpowers skills, enabling customization.
Automatic Triggering: Skills activate based on context, not explicit invocation.

​
Next Steps

Hooks System

Learn how hooks inject context at session start

Plugin System

Understand plugin manifests and distribution

Creating Skills

Write your own custom skills

Contributing

Contribute to Superpowers