Skip to content

An agentic skills framework & software development methodology that works.

Rewrite Codex docs for native skill discovery

Drew Ritter3626ccc53ea1
diff --git a/docs/README.codex.md b/docs/README.codex.md
index 7c7e0e862..a88bd3db5 100644
--- a/docs/README.codex.md
+++ b/docs/README.codex.md
@@ -1,6 +1,6 @@
# Superpowers for Codex
-Complete guide for using Superpowers with OpenAI Codex.
+Guide for using Superpowers with OpenAI Codex via native skill discovery.
## Quick Install
@@ -14,63 +14,68 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp
### Prerequisites
-- OpenAI Codex access
-- Shell access to install files
+- OpenAI Codex CLI
+- Node.js (for the installer script)
-### Installation Steps
+### Steps
-#### 1. Clone Superpowers
+1. Clone the repo:
+ ```bash
+ git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
+ ```
-```bash
-mkdir -p ~/.codex/superpowers
-git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
-```
+2. Run the installer:
+ ```bash
+ node ~/.codex/superpowers/.codex/install-codex.mjs
+ ```
-#### 2. Install Bootstrap
+3. Restart Codex.
-The bootstrap file is included in the repository at `.codex/superpowers-bootstrap.md`. Codex will automatically use it from the cloned location.
+The installer creates a symlink from `~/.agents/skills/superpowers` to the repo's `skills/` directory and adds a gatekeeper block to `~/.codex/AGENTS.md`. Existing users with the old bootstrap setup are migrated automatically.
-#### 3. Verify Installation
+### Windows
-Tell Codex:
+The installer tries symlinks first, then falls back to junctions (`mklink /J`) if symlinks require Developer Mode. Both work for Codex skill discovery.
+
+## 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:
```
-Run node $HOME/.codex/superpowers/.codex/superpowers-codex find-skills to show available skills
+~/.agents/skills/superpowers/ → ~/.codex/superpowers/skills/
```
-You should see a list of available skills with descriptions.
+A small gatekeeper block in `~/.codex/AGENTS.md` ensures Codex invokes `$using-superpowers` at session start, which enforces skill usage discipline across turns.
## Usage
-### Finding Skills
-
-```
-Run node $HOME/.codex/superpowers/.codex/superpowers-codex find-skills
-```
-
-### Loading a Skill
+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
-```
-Run node $HOME/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming
-```
+### Tool Mappings
-### Bootstrap All Skills
+Skills written for Claude Code reference tools that have Codex equivalents:
-```
-Run node $HOME/.codex/superpowers/.codex/superpowers-codex bootstrap
-```
+| 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 |
-This loads the complete bootstrap with all skill information.
+These mappings are included in the AGENTS.md gatekeeper block.
### Personal Skills
-Create your own skills in `~/.codex/skills/`:
+Create your own skills in `~/.agents/skills/`:
```bash
-mkdir -p ~/.codex/skills/my-skill
+mkdir -p ~/.agents/skills/my-skill
```
-Create `~/.codex/skills/my-skill/SKILL.md`:
+Create `~/.agents/skills/my-skill/SKILL.md`:
```markdown
---
@@ -83,72 +88,43 @@ description: Use when [condition] - [what it does]
[Your skill content here]
```
-Personal skills override superpowers skills with the same name.
-
-## Architecture
-
-### Codex CLI Tool
-
-**Location:** `~/.codex/superpowers/.codex/superpowers-codex`
-
-A Node.js CLI script that provides three commands:
-- `bootstrap` - Load complete bootstrap with all skills
-- `use-skill <name>` - Load a specific skill
-- `find-skills` - List all available skills
-
-### Shared Core Module
-
-**Location:** `~/.codex/superpowers/lib/skills-core.js`
-
-The Codex implementation uses the shared `skills-core` module (ES module format) for skill discovery and parsing. This is the same module used by the OpenCode plugin, ensuring consistent behavior across platforms.
+## Updating
-### Tool Mapping
+```bash
+cd ~/.codex/superpowers && git pull
+```
-Skills written for Claude Code are adapted for Codex with these mappings:
+Skills update instantly through the symlink.
-- `TodoWrite` → `update_plan`
-- `Task` with subagents → Use collab `spawn_agent` + `wait` when available; if collab is disabled, say so and proceed sequentially
-- `Subagent` / `Agent` tool mentions → Map to `spawn_agent` (collab) or sequential fallback when collab is disabled
-- `Skill` tool → `node $HOME/.codex/superpowers/.codex/superpowers-codex use-skill`
-- File operations → Native Codex tools
-
-## Updating
+## Uninstalling
```bash
-cd ~/.codex/superpowers
-git pull
+rm ~/.agents/skills/superpowers
```
+Then remove the block between `<!-- superpowers:begin -->` and `<!-- superpowers:end -->` from `~/.codex/AGENTS.md`.
+
## Troubleshooting
-### Skills not found
+### Skills not showing up
-1. Verify installation: `ls ~/.codex/superpowers/skills`
-2. Check CLI works: `node $HOME/.codex/superpowers/.codex/superpowers-codex find-skills`
-3. Verify skills have SKILL.md files
+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
-### CLI script not executable
+### Windows symlink issues
-```bash
-chmod +x ~/.codex/superpowers/.codex/superpowers-codex
-```
+If the installer reports symlink failure, ensure Developer Mode is enabled or run as administrator. The installer will attempt a junction fallback automatically.
-### Node.js errors
+### Node.js not found
-The CLI script requires Node.js. Verify:
+The installer requires Node.js. Verify:
```bash
node --version
```
-Should show v14 or higher (v18+ recommended for ES module support).
-
## Getting Help
- Report issues: https://github.com/obra/superpowers/issues
- Main documentation: https://github.com/obra/superpowers
-- Blog post: https://blog.fsck.com/2025/10/27/skills-for-openai-codex/
-
-## Note
-
-Codex support is experimental and may require refinement based on user feedback. If you encounter issues, please report them on GitHub.