2025-11-23 13:49:12 -08:00
# Superpowers for Codex
2026-02-05 16:03:38 -08:00
Guide for using Superpowers with OpenAI Codex via native skill discovery.
2025-11-23 13:49:12 -08:00
## Quick Install
Tell Codex:
```
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
```
## Manual Installation
### Prerequisites
2026-02-05 16:03:38 -08:00
- OpenAI Codex CLI
- Node.js (for the installer script)
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
### Steps
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
1. Clone the repo:
```bash
git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
` ``
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
2. Run the installer:
` ``bash
node ~/.codex/superpowers/.codex/install-codex.mjs
` ``
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
3. Restart Codex.
2025-11-23 13:49:12 -08:00
2026-02-05 16:34:05 -08:00
The installer links ` ~/.agents/skills/superpowers` to the repo's ` skills/` directory (symlink on macOS/Linux, junction on Windows) and adds a gatekeeper block to ` ~/.codex/AGENTS.md`. Existing users with the old bootstrap setup are migrated automatically.
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
### Windows
2025-11-23 13:49:12 -08:00
2026-02-05 16:34:05 -08:00
The installer creates a junction (` mklink /J`) on Windows, which works without Developer Mode. On macOS/Linux it creates a standard symlink. Both work for Codex skill discovery.
2026-02-05 16:03:38 -08:00
## How It Works
Codex has native skill discovery — it scans ` ~/.agents/skills/` at startup, parses SKILL.md frontmatter, and loads skills on demand. Superpowers skills are made visible through a single symlink:
2025-11-23 13:49:12 -08:00
` ``
2026-02-05 16:03:38 -08:00
~/.agents/skills/superpowers/ → ~/.codex/superpowers/skills/
2025-11-23 13:49:12 -08:00
` ``
2026-02-05 16:03:38 -08:00
A small gatekeeper block in ` ~/.codex/AGENTS.md` ensures Codex invokes ` $using-superpowers` at session start, which enforces skill usage discipline across turns.
2025-11-23 13:49:12 -08:00
## Usage
2026-02-05 16:03:38 -08:00
Skills are discovered automatically. Codex activates them when:
- You mention a skill by name (e.g., "use brainstorming")
- The task matches a skill's description
- The ` using-superpowers` skill directs Codex to use one
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
### Tool Mappings
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
Skills written for Claude Code reference tools that have Codex equivalents:
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
| Claude Code | Codex |
|-------------|-------|
| ` TodoWrite` | ` update_plan` |
| ` Task`/` Subagent` | ` spawn_agent` + ` wait` (or sequential if collab disabled) |
| ` Skill` tool | Native ` $skill-name` mention |
| ` Read`, ` Write`, ` Edit`, ` Bash` | Native equivalents |
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
These mappings are included in the AGENTS.md gatekeeper block.
2025-11-23 13:49:12 -08:00
### Personal Skills
2026-02-05 16:03:38 -08:00
Create your own skills in ` ~/.agents/skills/`:
2025-11-23 13:49:12 -08:00
` ``bash
2026-02-05 16:03:38 -08:00
mkdir -p ~/.agents/skills/my-skill
2025-11-23 13:49:12 -08:00
` ``
2026-02-05 16:03:38 -08:00
Create ` ~/.agents/skills/my-skill/SKILL.md`:
2025-11-23 13:49:12 -08:00
` ``markdown
---
name: my-skill
description: Use when [condition] - [what it does]
---
# My Skill
[Your skill content here]
` ``
2026-02-05 16:34:05 -08:00
The ` description` field is how Codex decides when to activate a skill automatically — write it as a clear trigger condition.
2026-02-05 16:03:38 -08:00
## Updating
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
` ``bash
cd ~/.codex/superpowers && git pull
` ``
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
Skills update instantly through the symlink.
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
## Uninstalling
2025-11-23 13:49:12 -08:00
` ``bash
2026-02-05 16:03:38 -08:00
rm ~/.agents/skills/superpowers
2025-11-23 13:49:12 -08:00
` ``
2026-02-05 16:03:38 -08:00
Then remove the block between ` <!-- superpowers:begin -->` and ` <!-- superpowers:end -->` from ` ~/.codex/AGENTS.md`.
2025-11-23 13:49:12 -08:00
## Troubleshooting
2026-02-05 16:03:38 -08:00
### Skills not showing up
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
1. Verify the symlink: ` ls -la ~/.agents/skills/superpowers`
2. Check skills exist: ` ls ~/.codex/superpowers/skills`
3. Restart Codex — skills are discovered at startup
2025-11-23 13:49:12 -08:00
2026-02-05 16:34:05 -08:00
### Windows junction issues
2025-11-23 13:49:12 -08:00
2026-02-05 16:34:05 -08:00
The installer creates junctions on Windows, which normally work without special permissions. If junction creation fails, try running PowerShell as administrator.
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
### Node.js not found
2025-11-23 13:49:12 -08:00
2026-02-05 16:03:38 -08:00
The installer requires Node.js. Verify:
2025-11-23 13:49:12 -08:00
` ``bash
node --version
` ``
## Getting Help
- Report issues: https://github.com/obra/superpowers/issues
- Main documentation: https://github.com/obra/superpowers