blob: e43004f42d739882e65fd4cd66d5ac52357aa5ac (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
# Superpowers for Codex
Complete guide for using Superpowers with OpenAI Codex.
## 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 access
- Shell access to install files
### Installation Steps
#### 1. Clone Superpowers
```bash
mkdir -p ~/.codex/superpowers
git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
```
#### 2. Install Bootstrap
The bootstrap file is included in the repository at `.codex/superpowers-bootstrap.md`. Codex will automatically use it from the cloned location.
#### 3. Verify Installation
Tell Codex:
```
Run ~/.codex/superpowers/.codex/superpowers-codex find-skills to show available skills
```
You should see a list of available skills with descriptions.
## Usage
### Finding Skills
```
Run ~/.codex/superpowers/.codex/superpowers-codex find-skills
```
### Loading a Skill
```
Run ~/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming
```
### Bootstrap All Skills
```
Run ~/.codex/superpowers/.codex/superpowers-codex bootstrap
```
This loads the complete bootstrap with all skill information.
### Personal Skills
Create your own skills in `~/.codex/skills/`:
```bash
mkdir -p ~/.codex/skills/my-skill
```
Create `~/.codex/skills/my-skill/SKILL.md`:
```markdown
---
name: my-skill
description: Use when [condition] - [what it does]
---
# My Skill
[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.
### Tool Mapping
Skills written for Claude Code are adapted for Codex with these mappings:
- `TodoWrite` → `update_plan`
- `Task` with subagents → Tell user subagents aren't available, do work directly
- `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill`
- File operations → Native Codex tools
## Updating
```bash
cd ~/.codex/superpowers
git pull
```
## Troubleshooting
### Skills not found
1. Verify installation: `ls ~/.codex/superpowers/skills`
2. Check CLI works: `~/.codex/superpowers/.codex/superpowers-codex find-skills`
3. Verify skills have SKILL.md files
### CLI script not executable
```bash
chmod +x ~/.codex/superpowers/.codex/superpowers-codex
```
### Node.js errors
The CLI script 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.
|