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

> Learn how Superpowers integrates AI coding agents like Claude Code and Codex, enabling seamless discovery, loading, and execution of workflow capabilities without agent code changes.

- Repository: [Jesse Vincent/superpowers](https://github.com/obra/superpowers)
- Tags: deep-dive
- Published: 2026-02-16

---

**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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/.claude-plugin/plugin.json). This plugin registers the Superpowers skill collection and installs the mandatory `using-superpowers` skill. Users activate the integration by running:

```bash
/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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:

```bash

# 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`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) for skill processing. This module exports three critical functions: `findSkillsInDir` recursively discovers all [`SKILL.md`](https://github.com/obra/superpowers/blob/main/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:**

```bash

# 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:**

```bash

# 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`](https://github.com/obra/superpowers/blob/main/.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`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) for parsing [`SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/.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`](https://github.com/obra/superpowers/blob/main/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.