How Superpowers Supports AI Coding Agents: Claude Code and Codex Integration

Superpowers provides a unified skill ecosystem that enables AI coding agents like Claude Code and Codex to discover, load, and execute workflow-driven capabilities without requiring any code changes in the agents themselves.

The obra/superpowers repository implements a portable skill system designed specifically for AI coding agents. By standardizing how capabilities are defined, discovered, and enforced, Superpowers allows both Claude Code and Codex to share identical development workflows—from test-driven development to code review protocols—using the same underlying skill files.

What Is the Superpowers Skill System?

Superpowers organizes capabilities as skills—self-contained workflow definitions stored in SKILL.md files. Each skill includes YAML front-matter specifying its name and description, followed by markdown instructions that guide the agent through a specific process. The system relies on lib/skills-core.js to parse these files, resolve conflicts between personal and shared skills, and strip front-matter before execution.

How Superpowers Integrates with Claude Code

Plugin Architecture and Registration

Claude Code integrates with Superpowers through a dedicated marketplace plugin defined in .claude-plugin/plugin.json. This plugin registers the Superpowers skill collection and installs the mandatory using-superpowers skill. Users activate the integration by running:

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Once installed, the plugin creates a symlink at ~/.claude/skills/superpowers/ pointing to the Superpowers skill directory, making all workflows immediately available to Claude Code's built-in Skill tool.

Skill Discovery and Loading

Claude Code's Skill tool scans ~/.claude/skills/ for SKILL.md files. When a user request matches a skill's description front-matter, Claude Code loads the full skill file. The lib/skills-core.js module handles the parsing logic, using findSkillsInDir to discover files and stripFrontmatter to clean the content before execution. The resolveSkillPath function manages shadowing, allowing personal skills in ~/.claude/skills/ to override Superpowers defaults while maintaining the same interface.

The using-superpowers Enforcement Rule

The skills/using-superpowers/SKILL.md file defines a mandatory rule that enforces a "skill-first" check on every interaction. Before responding to any request, Claude Code must verify whether a relevant Superpowers skill exists. If found, the agent executes the skill's prescribed workflow—such as brainstorming alternatives, creating implementation plans, or spawning sub-agents—rather than improvising a response. This ensures consistent, reproducible development practices across all sessions.

How Superpowers Integrates with Codex

Native Filesystem Discovery

Unlike Claude Code's plugin-based approach, Codex supports native skill discovery through filesystem scanning. At startup, Codex automatically searches ~/.agents/skills/ for SKILL.md files and loads any discovered workflows. Superpowers leverages this native capability by providing a simple symlink that exposes its entire skill library to Codex without requiring any custom plugins or code modifications.

Symlink Installation Method

Installing Superpowers for Codex requires only three steps. First, clone the repository to ~/.codex/superpowers. Then create a symlink from the Superpowers skills directory to Codex's skill path:

# Linux and macOS

mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers

# Windows PowerShell

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"

Finally, restart Codex. The agent will automatically discover all Superpowers skills through its native scanner, including the mandatory using-superpowers rule that enforces workflow-driven responses.

Shared Core Architecture

The skills-core.js Parser

Both Claude Code and Codex rely on lib/skills-core.js for skill processing. This module exports three critical functions: findSkillsInDir recursively discovers all SKILL.md files in a directory tree; resolveSkillPath handles skill shadowing by checking user directories before system defaults; and stripFrontmatter removes YAML metadata before passing the workflow instructions to the agent. By centralizing this logic, Superpowers ensures identical skill behavior across both platforms.

Skill Shadowing and Resolution

The resolveSkillPath function implements a precedence system that allows personal skills to override Superpowers defaults. When searching for a skill named brainstorming, the parser first checks ~/.claude/skills/ (for Claude Code) or ~/.agents/skills/ (for Codex) before falling back to the Superpowers system directory. This shadowing mechanism lets teams customize workflows while maintaining the core Superpowers infrastructure.

Installing Superpowers for AI Coding Agents

To begin using Superpowers with your preferred AI coding agent, follow the platform-specific installation steps below.

For Claude Code:

# Add the Superpowers marketplace (one-time setup)

/plugin marketplace add obra/superpowers-marketplace

# Install the plugin

/plugin install superpowers@superpowers-marketplace

# Verify installation by starting a new session and requesting:

# "Help me plan a new feature"

# Claude will automatically invoke the brainstorming skill.

For Codex:

# Clone the repository

git clone https://github.com/obra/superpowers.git ~/.codex/superpowers

# Create the skills symlink (Linux/macOS)

mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers

# Or on Windows PowerShell

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"

# Restart Codex, then test with:

# codex "Write a test-driven implementation for a stack."

Summary

• Superpowers provides a unified skill ecosystem for AI coding agents, enabling both Claude Code and Codex to execute identical workflows without platform-specific code.
• Claude Code integrates via a marketplace plugin (.claude-plugin/plugin.json) that registers skills under ~/.claude/skills/superpowers/.
• Codex uses native filesystem discovery through a symlink from ~/.agents/skills/superpowers to the Superpowers skill directory.
• Both agents rely on lib/skills-core.js for parsing SKILL.md files, resolving skill shadowing, and stripping front-matter.
• The using-superpowers skill enforces a mandatory "skill-first" check, ensuring agents consult relevant workflows before improvising responses.

Frequently Asked Questions

Do I need to modify Claude Code or Codex source code to use Superpowers?

No. Superpowers requires zero modifications to either agent. Claude Code loads capabilities through its official plugin marketplace system defined in .claude-plugin/plugin.json, while Codex discovers skills through its native filesystem scanner. Both methods use standard extension points provided by the agents themselves.

Can I override a Superpowers skill with my own custom version?

Yes. The lib/skills-core.js module implements skill shadowing through the resolveSkillPath function. When searching for a skill, the parser checks user-specific directories (~/.claude/skills/ or ~/.agents/skills/) before falling back to system defaults, allowing personal overrides while maintaining the core workflow structure.

What happens if I install Superpowers for both Claude Code and Codex simultaneously?

Both agents can share the same Superpowers installation. When installing for Codex, you clone the repository to ~/.codex/superpowers. When installing for Claude Code, the plugin creates a separate symlink at ~/.claude/skills/superpowers. Both symlinks point to the same underlying skill files, ensuring workflow consistency across agents while maintaining separate configuration scopes.

Does the using-superpowers skill restrict what agents can do?

The using-superpowers skill does not restrict capabilities but enforces a disciplined workflow. Before responding to any request, the agent must check whether a relevant skill exists for the task. If found, the agent follows the skill's prescribed steps—such as brainstorming, planning, or test-driven development—rather than improvising. This ensures consistent, reproducible outputs without limiting the agent's ability to handle diverse tasks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}