Install on Codex

Install Superpowers on OpenAI Codex via native skill discovery

Install Superpowers on OpenAI Codex using native skill discovery. Codex automatically discovers skills from ~/.agents/skills/, making installation a simple clone and symlink operation.

Prerequisites

• OpenAI Codex CLI installed
• Git installed
• Terminal access (Command Prompt, PowerShell, or Bash)

Quick Install

The fastest way to install is to tell Codex to do it:

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

Codex will read the installation script and execute it automatically.

Manual Installation

For manual control, follow these platform-specific steps:

macOS / Linux

1. Clone the Repository

   Clone Superpowers to the Codex directory:

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

   Create the symlink for skill discovery:

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

   This makes Superpowers skills discoverable by Codex.

3. Restart Codex

   Quit and relaunch the Codex CLI. Skills are discovered at startup.

4. Verify Installation

   Check the symlink was created correctly:

   ls -la ~/.agents/skills/superpowers
   

   You should see a symlink pointing to ~/.codex/superpowers/skills.

Windows

1. Clone the Repository

   Open PowerShell and clone Superpowers:

   git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.codex\superpowers"
   
2. Create Skills Junction

   Create a directory junction (works without Developer Mode):

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

   Windows junctions work like symlinks but don’t require special permissions.

3. Restart Codex

   Close and reopen Codex CLI. Skills load at startup.

4. Verify Installation

   Check the junction was created:

   Get-ChildItem "$env:USERPROFILE\.agents\skills" | Where-Object { $_.LinkType }
   

   Look for <JUNCTION> next to superpowers.

How It Works

Codex uses native skill discovery:

1. At startup, Codex scans ~/.agents/skills/
2. It parses SKILL.md files and reads YAML frontmatter
3. Skills are loaded on demand when:
   • You mention a skill by name
   • The task matches a skill’s description
   • Another skill directs Codex to use one

The symlink makes all Superpowers skills visible to this discovery process:

~/.agents/skills/superpowers/ → ~/.codex/superpowers/skills/

Verifying Skills Are Active

Test automatic skill activation:

Planning

Help me plan a new feature

Codex should automatically activate the relevant skill (brainstorming, systematic-debugging, or requesting-code-review).

Creating Personal Skills

Add your own skills alongside Superpowers:

1. Create Skill Directory

   mkdir -p ~/.agents/skills/my-skill
   
2. Write Skill File

   Create ~/.agents/skills/my-skill/SKILL.md:

   ---
   name: my-skill
   description: Use when [condition] - [what it does]
   ---
   
   # My Skill
   
   [Your skill instructions here]
   

   The description field determines when Codex activates your skill automatically.

3. Restart Codex

   Restart Codex to discover the new skill.

Updating

Update to the latest version:

cd ~/.codex/superpowers && git pull

Skills update instantly through the symlink—no restart needed for skill content changes.

Migrating from Old Bootstrap

If you installed Superpowers before native skill discovery:

1. Update the Repository

   cd ~/.codex/superpowers && git pull
   
2. Create Skills Symlink

   Follow the manual installation steps above to create the symlink.

3. Remove Old Bootstrap

   Edit ~/.codex/AGENTS.md and remove any blocks referencing superpowers-codex bootstrap.

4. Restart Codex

   Restart Codex CLI to apply changes.

Troubleshooting

Skills not showing up

Symptom: Codex doesn’t recognize Superpowers skills

Solutions:

• Verify symlink exists: ls -la ~/.agents/skills/superpowers
• Check skills directory: ls ~/.codex/superpowers/skills
• Restart Codex—skills are discovered at startup
• On Windows, verify junction: dir /AL %USERPROFILE%\.agents\skills

Windows junction creation fails

Symptom: Error creating junction with mklink /J

Solutions:

• Junctions normally work without special permissions
• Try running PowerShell as Administrator
• Verify paths exist: $env:USERPROFILE\.codex\superpowers\skills

Skills exist but don't activate

Symptom: Skills are present but Codex doesn’t use them

Solutions:

• Check SKILL.md files have valid YAML frontmatter
• Verify description field clearly states activation conditions
• Explicitly request a skill: “use brainstorming skill”
• Check Codex logs for skill loading errors

Git clone fails

Symptom: Cannot clone repository

Solutions:

• Check internet connection
• Verify Git is installed: git --version
• Try HTTPS URL: https://github.com/obra/superpowers.git
• Check GitHub status: https://www.githubstatus.com

Uninstalling

Remove the symlink:

rm ~/.agents/skills/superpowers

Windows:

Remove-Item "$env:USERPROFILE\.agents\skills\superpowers"

Optionally delete the clone:

rm -rf ~/.codex/superpowers

Windows:

Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\superpowers"

Next Steps

Quick Start

Learn the Superpowers workflow

Skills Library

Explore available skills

Writing Skills

Create custom skills

Troubleshooting

Common issues and solutions