Skip to content

An agentic skills framework & software development methodology that works.

Polish docs from 5-agent review

Drew Ritterbcccc692717f
diff --git a/.codex/INSTALL.md b/.codex/INSTALL.md
index 354ad6553..af335ad9a 100644
--- a/.codex/INSTALL.md
+++ b/.codex/INSTALL.md
@@ -1,6 +1,11 @@
# Installing Superpowers for Codex
-Quick setup to enable superpowers skills in Codex via native skill discovery.
+Quick setup to enable superpowers skills in Codex. The installer links your skills into Codex's native discovery path so they load automatically.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) (v16+)
+- Git
## Installation
@@ -14,21 +19,31 @@ Quick setup to enable superpowers skills in Codex via native skill discovery.
node ~/.codex/superpowers/.codex/install-codex.mjs
```
-3. **Restart Codex** to discover the skills.
+3. **Restart Codex** (quit and relaunch the CLI) to discover the skills.
+
+**Windows:** The installer creates a junction (`mklink /J`), which works without Developer Mode.
## What the installer does
-- Creates a symlink: `~/.agents/skills/superpowers` → `~/.codex/superpowers/skills`
-- Adds a small gatekeeper block to `~/.codex/AGENTS.md`
+- Links `~/.agents/skills/superpowers` → `~/.codex/superpowers/skills` (symlink on macOS/Linux, junction on Windows)
+- Adds a gatekeeper block to `~/.codex/AGENTS.md` that tells Codex to use superpowers skills
- If you had the old bootstrap setup, it removes it automatically
+## Verify
+
+```bash
+ls -la ~/.agents/skills/superpowers
+```
+
+You should see a symlink (or junction) pointing to your superpowers skills directory.
+
## Updating
```bash
cd ~/.codex/superpowers && git pull
```
-Skills update instantly through the symlink.
+Skills update instantly through the link.
## Uninstalling
@@ -36,4 +51,4 @@ Skills update instantly through the symlink.
rm ~/.agents/skills/superpowers
```
-Then remove the block between `<!-- superpowers:begin -->` and `<!-- superpowers:end -->` from `~/.codex/AGENTS.md`.
+Then remove the block between `<!-- superpowers:begin -->` and `<!-- superpowers:end -->` from `~/.codex/AGENTS.md`. Optionally delete the clone: `rm -rf ~/.codex/superpowers`.
diff --git a/.codex/install-codex.mjs b/.codex/install-codex.mjs
index d878b0a2b..5db43e333 100644
--- a/.codex/install-codex.mjs
+++ b/.codex/install-codex.mjs
@@ -64,19 +64,21 @@ function createSymlink() {
}
}
- // Create the symlink (or junction on Windows)
+ // Create the link (symlink on macOS/Linux, junction on Windows)
+ const linkType = isWindows ? 'junction' : 'dir';
+ const linkLabel = isWindows ? 'junction' : 'symlink';
try {
- symlinkSync(repoSkillsDir, symlinkPath, 'junction');
- console.log(`✓ Created symlink: ${symlinkPath} → ${repoSkillsDir}`);
+ symlinkSync(repoSkillsDir, symlinkPath, linkType);
+ console.log(`✓ Created ${linkLabel}: ${symlinkPath} → ${repoSkillsDir}`);
} catch (err) {
if (isWindows) {
- // Symlink failed on Windows — try junction via mklink /J
+ // Node API failed on Windows — try junction via cmd.exe
try {
execSync(`cmd /c mklink /J "${symlinkPath}" "${repoSkillsDir}"`, { stdio: 'pipe' });
console.log(`✓ Created junction: ${symlinkPath} → ${repoSkillsDir}`);
} catch (junctionErr) {
- console.error(`✗ Failed to create symlink or junction: ${junctionErr.message}`);
- console.error(` On Windows, enable Developer Mode or run as administrator.`);
+ console.error(`✗ Failed to create junction: ${junctionErr.message}`);
+ console.error(` Try running PowerShell as administrator.`);
process.exit(1);
}
} else {
diff --git a/docs/README.codex.md b/docs/README.codex.md
index a88bd3db5..b230de10f 100644
--- a/docs/README.codex.md
+++ b/docs/README.codex.md
@@ -31,11 +31,11 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp
3. Restart Codex.
-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.
+The installer links `~/.agents/skills/superpowers` to the repo's `skills/` directory (symlink on macOS/Linux, junction on Windows) and adds a gatekeeper block to `~/.codex/AGENTS.md`. Existing users with the old bootstrap setup are migrated automatically.
### Windows
-The installer tries symlinks first, then falls back to junctions (`mklink /J`) if symlinks require Developer Mode. Both work for Codex skill discovery.
+The installer creates a junction (`mklink /J`) on Windows, which works without Developer Mode. On macOS/Linux it creates a standard symlink. Both work for Codex skill discovery.
## How It Works
@@ -88,6 +88,8 @@ description: Use when [condition] - [what it does]
[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
@@ -112,9 +114,9 @@ Then remove the block between `<!-- superpowers:begin -->` and `<!-- superpowers
2. Check skills exist: `ls ~/.codex/superpowers/skills`
3. Restart Codex — skills are discovered at startup
-### Windows symlink issues
+### Windows junction issues
-If the installer reports symlink failure, ensure Developer Mode is enabled or run as administrator. The installer will attempt a junction fallback automatically.
+The installer creates junctions on Windows, which normally work without special permissions. If junction creation fails, try running PowerShell as administrator.
### Node.js not found