> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt
> Use this file to discover all available pages before exploring further.

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

```text theme={null}
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:

<Tabs>
  <Tab title="macOS / Linux">
    <Steps>
      <Step title="Clone the Repository">
        Clone Superpowers to the Codex directory:

        ```bash theme={null}
        git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
        ```
      </Step>

      <Step title="Create Skills Symlink">
        Create the symlink for skill discovery:

        ```bash theme={null}
        mkdir -p ~/.agents/skills
        ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
        ```

        This makes Superpowers skills discoverable by Codex.
      </Step>

      <Step title="Restart Codex">
        Quit and relaunch the Codex CLI. Skills are discovered at startup.
      </Step>

      <Step title="Verify Installation">
        Check the symlink was created correctly:

        ```bash theme={null}
        ls -la ~/.agents/skills/superpowers
        ```

        You should see a symlink pointing to `~/.codex/superpowers/skills`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windows">
    <Steps>
      <Step title="Clone the Repository">
        Open PowerShell and clone Superpowers:

        ```powershell theme={null}
        git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.codex\superpowers"
        ```
      </Step>

      <Step title="Create Skills Junction">
        Create a directory junction (works without Developer Mode):

        ```powershell theme={null}
        New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
        cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
        ```

        <Note>
          Windows junctions work like symlinks but don't require special permissions.
        </Note>
      </Step>

      <Step title="Restart Codex">
        Close and reopen Codex CLI. Skills load at startup.
      </Step>

      <Step title="Verify Installation">
        Check the junction was created:

        ```powershell theme={null}
        Get-ChildItem "$env:USERPROFILE\.agents\skills" | Where-Object { $_.LinkType }
        ```

        Look for `<JUNCTION>` next to `superpowers`.
      </Step>
    </Steps>
  </Tab>
</Tabs>

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

<CodeGroup>
  ```text Planning theme={null}
  Help me plan a new feature
  ```

  ```text Debugging   theme={null}
  Debug this intermittent failure
  ```

  ```text Code Review theme={null}
  Review my changes against the plan
  ```
</CodeGroup>

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

## Creating Personal Skills

Add your own skills alongside Superpowers:

<Steps>
  <Step title="Create Skill Directory">
    ```bash theme={null}
    mkdir -p ~/.agents/skills/my-skill
    ```
  </Step>

  <Step title="Write Skill File">
    Create `~/.agents/skills/my-skill/SKILL.md`:

    ```markdown theme={null}
    ---
    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.
  </Step>

  <Step title="Restart Codex">
    Restart Codex to discover the new skill.
  </Step>
</Steps>

## Updating

Update to the latest version:

```bash theme={null}
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:

<Steps>
  <Step title="Update the Repository">
    ```bash theme={null}
    cd ~/.codex/superpowers && git pull
    ```
  </Step>

  <Step title="Create Skills Symlink">
    Follow the manual installation steps above to create the symlink.
  </Step>

  <Step title="Remove Old Bootstrap">
    Edit `~/.codex/AGENTS.md` and remove any blocks referencing `superpowers-codex bootstrap`.
  </Step>

  <Step title="Restart Codex">
    Restart Codex CLI to apply changes.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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](https://www.githubstatus.com)
  </Accordion>
</AccordionGroup>

## Uninstalling

Remove the symlink:

```bash theme={null}
rm ~/.agents/skills/superpowers
```

**Windows:**

```powershell theme={null}
Remove-Item "$env:USERPROFILE\.agents\skills\superpowers"
```

Optionally delete the clone:

```bash theme={null}
rm -rf ~/.codex/superpowers
```

**Windows:**

```powershell theme={null}
Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\superpowers"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/getting-started/quick-start">
    Learn the Superpowers workflow
  </Card>

  <Card title="Skills Library" icon="book" href="/skills/overview">
    Explore available skills
  </Card>

  <Card title="Writing Skills" icon="pen" href="/customization/writing-skills">
    Create custom skills
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>