Skip to main content
Superpowers integrates with Codex through its native skill discovery system. Codex scans ~/.agents/skills/ at startup, parses SKILL.md frontmatter, and loads skills on demand.

​
Quick install

Tell Codex: 
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
Codex will fetch and execute the install steps automatically.

​
Manual installation

1

Clone the repository

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

Create the skills symlink

mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
This makes all Superpowers skills visible to Codex’s skill discovery.
3

Restart Codex

Skills are discovered at startup. Restart Codex to pick up the new skills.
4

Enable multi-agent support (optional)

Skills like subagent-driven-development and dispatching-parallel-agents require Codex’s multi-agent feature. Add to your Codex config:
[features]
multi_agent = true

​
Windows

Use a junction instead of a symlink (no Developer Mode required): 
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"

​
How it works

Codex scans ~/.agents/skills/ on startup and parses the description field in each SKILL.md. Skills activate 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
The symlink ~/.agents/skills/superpowers/ → ~/.codex/superpowers/skills/ makes all 14 Superpowers skills discoverable with no additional configuration.

​
Personal skills

Create your own skills in ~/.agents/skills/: 
mkdir -p ~/.agents/skills/my-skill
Create ~/.agents/skills/my-skill/SKILL.md: 
---
name: my-skill
description: Use when [condition] — [what it does]
---

# My Skill

Your skill content here.

​
Updating

cd ~/.codex/superpowers && git pull
Skills update instantly through the symlink — no restart needed.

​
Uninstalling

rm ~/.agents/skills/superpowers
# optionally: rm -rf ~/.codex/superpowers
Windows: 
Remove-Item "$env:USERPROFILE\.agents\skills\superpowers"
# optionally: Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\superpowers"

​
Troubleshooting

  1. Verify the symlink: ls -la ~/.agents/skills/superpowers
  2. Confirm skills exist: ls ~/.codex/superpowers/skills
  3. Restart Codex — discovery happens at startup
Junctions normally work without special permissions. If creation fails, run PowerShell as administrator.

Build docs developers (and LLMs) love

Get started for freeTalk to us