diff --git a/.codex/INSTALL.md b/.codex/INSTALL.md deleted file mode 100644 index c415e2e1..00000000 --- a/.codex/INSTALL.md +++ /dev/null @@ -1,67 +0,0 @@ -# Installing Superpowers for Codex - -Enable superpowers skills in Codex via native skill discovery. Just clone and symlink. - -## Prerequisites - -- Git - -## Installation - -1. **Clone the superpowers repository:** - ```bash - git clone https://github.com/obra/superpowers.git ~/.codex/superpowers - ``` - -2. **Create the skills symlink:** - ```bash - mkdir -p ~/.agents/skills - ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers - ``` - - **Windows (PowerShell):** - ```powershell - New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills" - cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills" - ``` - -3. **Restart Codex** (quit and relaunch the CLI) to discover the skills. - -## Migrating from old bootstrap - -If you installed superpowers before native skill discovery, you need to: - -1. **Update the repo:** - ```bash - cd ~/.codex/superpowers && git pull - ``` - -2. **Create the skills symlink** (step 2 above) — this is the new discovery mechanism. - -3. **Remove the old bootstrap block** from `~/.codex/AGENTS.md` — any block referencing `superpowers-codex bootstrap` is no longer needed. - -4. **Restart Codex.** - -## Verify - -```bash -ls -la ~/.agents/skills/superpowers -``` - -You should see a symlink (or junction on Windows) pointing to your superpowers skills directory. - -## Updating - -```bash -cd ~/.codex/superpowers && git pull -``` - -Skills update instantly through the symlink. - -## Uninstalling - -```bash -rm ~/.agents/skills/superpowers -``` - -Optionally delete the clone: `rm -rf ~/.codex/superpowers`. diff --git a/docs/README.codex.md b/docs/README.codex.md deleted file mode 100644 index 97e2319c..00000000 --- a/docs/README.codex.md +++ /dev/null @@ -1,126 +0,0 @@ -# Superpowers for Codex - -Guide for using Superpowers with OpenAI Codex via native skill discovery. - -## Quick Install - -Tell Codex: - -``` -Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md -``` - -## Manual Installation - -### Prerequisites - -- OpenAI Codex CLI -- Git - -### Steps - -1. Clone the repo: - ```bash - git clone https://github.com/obra/superpowers.git ~/.codex/superpowers - ``` - -2. Create the skills symlink: - ```bash - mkdir -p ~/.agents/skills - ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers - ``` - -3. Restart Codex. - -4. **For subagent skills** (optional): Skills like `dispatching-parallel-agents` and `subagent-driven-development` require Codex's multi-agent feature. Add to your Codex config: - ```toml - [features] - multi_agent = true - ``` - -### Windows - -Use a junction instead of a symlink (works without Developer Mode): - -```powershell -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 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: - -``` -~/.agents/skills/superpowers/ → ~/.codex/superpowers/skills/ -``` - -The `using-superpowers` skill is discovered automatically and enforces skill usage discipline — no additional configuration needed. - -## Usage - -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 - -### Personal Skills - -Create your own skills in `~/.agents/skills/`: - -```bash -mkdir -p ~/.agents/skills/my-skill -``` - -Create `~/.agents/skills/my-skill/SKILL.md`: - -```markdown ---- -name: my-skill -description: Use when [condition] - [what it does] ---- - -# My Skill - -[Your skill content here] -``` - -The `description` field is how Codex decides when to activate a skill automatically — write it as a clear trigger condition. - -## Updating - -```bash -cd ~/.codex/superpowers && git pull -``` - -Skills update instantly through the symlink. - -## Uninstalling - -```bash -rm ~/.agents/skills/superpowers -``` - -**Windows (PowerShell):** -```powershell -Remove-Item "$env:USERPROFILE\.agents\skills\superpowers" -``` - -Optionally delete the clone: `rm -rf ~/.codex/superpowers` (Windows: `Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\superpowers"`). - -## Troubleshooting - -### Skills not showing up - -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 - -### Windows junction issues - -Junctions normally work without special permissions. If creation fails, try running PowerShell as administrator. - -## Getting Help - -- Report issues: https://github.com/obra/superpowers/issues -- Main documentation: https://github.com/obra/superpowers diff --git a/skills/using-superpowers/references/codex-tools.md b/skills/using-superpowers/references/codex-tools.md index 539b2b1c..b7a5745b 100644 --- a/skills/using-superpowers/references/codex-tools.md +++ b/skills/using-superpowers/references/codex-tools.md @@ -65,10 +65,11 @@ specified in the instructions above. ### When this workaround can be removed -This approach compensates for Codex's plugin system not yet supporting an `agents` -field in `plugin.json`. When `RawPluginManifest` gains an `agents` field, the -plugin can symlink to `agents/` (mirroring the existing `skills/` symlink) and -skills can dispatch named agent types directly. +This approach compensates for Codex not yet exposing plugin-packaged custom +agents as named `spawn_agent` targets. OpenAI plugin examples can include +plugin-level `agents/` directories, but skills still need to read those prompts +and spawn a built-in agent role. When Codex exposes plugin agents as callable +named agent types, this manual prompt-loading workaround can be removed. ## Environment Detection