superpowers

What you will run into

What this tool solves: making your Agent work by software engineering methodology — design before code, test-driven development, systematic debugging, subagent-driven development. Superpowers is a methodology framework of 14 composable skills: the Agent auto-triggers skills by the SKILL.md description (e.g. brainstorming + TDD automatically before writing code). When to use it:

• You want the Agent's coding behavior to go from "write directly" to "think first, then write";
• You want this methodology set: brainstorming / test-driven-development / systematic-debugging / subagent-driven-development;
• You're on Codex (official Codex form = copy skills/ to ~/.codex/skills/superpowers, verified in this environment).

When not to use it: you only want tools, not methodology constraints — it changes how the Agent works (that's the design intent). Notes: pure skill package — no CLI/daemon/port; install = copy the skills directory; skills are auto-triggered by the Agent, no manual commands.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

How it works: the official Codex form = copy the repo's skills/ to ~/.codex/skills/superpowers (plain file copy, 14 skill directories + SKILL.md). After install the Agent auto-triggers skills by description. Method B: the official Claude Code plugin marketplace (/plugin install superpowers, not tested — not logged in). Key concepts:

• Auto-trigger: the Agent reads the SKILL.md description and loads the skill when a task matches;
• Methodology skills: brainstorming / TDD / systematic-debugging / subagent-driven-development, 14 in total;
• Same-directory write surface: skill subdirectory names are unique; another skill set with the same name overwrites when installed later.

Where it writes: ~/.codex/skills/superpowers/ (Codex form); the Claude form writes ~/.claude/skills/ or via plugin registration.

Step by step

Step 1: Copy the skill directory (why direct copy: pure-file skill package, no dependencies, no registration)

Why: download the tarball pinned at tag v6.3.0 (fixed tag, no drift), extract, copy skills/ to ~/.codex/skills/superpowers. Reinstalling overwrites the same-named directory. Install = plain file copy, no dependencies, no registration, no background process.

curl -sL -o /tmp/superpowers.tar.gz https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0
rm -rf /tmp/superpowers-src && mkdir -p /tmp/superpowers-src
tar xzf /tmp/superpowers.tar.gz -C /tmp/superpowers-src --strip-components=1
mkdir -p ~/.codex/skills && cp -r /tmp/superpowers-src/skills ~/.codex/skills/superpowers
test -f ~/.codex/skills/superpowers/brainstorming/SKILL.md && echo "superpowers installed: OK"

Expected output: superpowers installed: OK After install, confirm:

• output shows superpowers installed: OK;
• ls ~/.codex/skills/superpowers has 14 skill directories.

Stuck? How to recover:

• codeload download failed → retry on another network (codeload direct verified 1.7s, generally reachable);
• skills not active → confirm they were copied to the skill directory the Agent actually reads (Codex: ~/.codex/skills/).

Step 2: Confirm the skills are in place (verified in this environment)

Why: list the skill directories to confirm the 14 skills; skills are auto-triggered by the Agent, no manual commands.

ls ~/.codex/skills/superpowers

Expected output: 14 个技能目录（brainstorming / test-driven-development / systematic-debugging / subagent-driven-development 等） After install, confirm:

• output includes brainstorming, test-driven-development etc.

Stuck? How to recover:

• directories incomplete → redo the copy in Step 1.

Step 3: Update to the latest (re-download and overwrite) or install the Claude form (as needed)

Why: update = re-download and overwrite (fixed tag, no drift); the Claude Code form uses the official plugin marketplace (not tested — not logged in); you can also manually copy to ~/.claude/skills/superpowers.

curl -sL -o /tmp/superpowers.tar.gz https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0 && rm -rf /tmp/superpowers-src && mkdir -p /tmp/superpowers-src && tar xzf /tmp/superpowers.tar.gz -C /tmp/superpowers-src --strip-components=1 && cp -r /tmp/superpowers-src/skills ~/.codex/skills/superpowers && echo "updated: OK"

Expected output: updated: OK Claude form check:

ls ~/.claude/skills/superpowers 2>/dev/null || echo "未安装 Claude 形态"

Expected output: 目录列表或未安装提示 Stuck? How to recover:

• download failed → retry on another network (codeload direct verified 1.7s);
• Claude plugin form won't install → confirm Claude Code is logged in (not tested in this environment).

How to confirm it works

Step 1: Confirm the skill directory is in place

Why: install is a plain file copy — files on disk means installed. test -f marker file exists + the directory listing includes the core skill directories.

test -f ~/.codex/skills/superpowers/brainstorming/SKILL.md && echo "installed: OK" || echo "installed: MISSING"
ls ~/.codex/skills/superpowers

Expected output: installed: OK + 14 个技能目录（brainstorming / test-driven-development / systematic-debugging / subagent-driven-development 等） Stuck? How to recover:

• directories incomplete → redo the copy in Step 1 of "Step by step";
• skills not active → confirm they were copied to the skill directory the Agent actually reads (Codex: ~/.codex/skills/).

Step 2: Confirm the Agent can trigger (optional)

Why: skills are auto-triggered by the Agent, no manual commands; in a new session, ask the Agent to handle a matching scenario (e.g. a debugging task) — if it references brainstorming/systematic-debugging, the path is confirmed.

# 无命令：新建会话让 Agent 触发技能即可

Expected output: Agent 会话中技能被自动引用（无需手动调用） Stuck? How to recover:

• Agent doesn't reference skills → confirm the skill directory is on the Agent's actual read path (~/.codex/skills/), restart the session if needed.

Other environments

• Update: re-download and overwrite the fixed tag (v6.3.0, no drift); reinstalling overwrites the same-named directory.
• Claude form: official plugin marketplace (not tested — not logged in) or manual copy to ~/.claude/skills/superpowers; judged possible-conflict with ruflo (Claude form shares the ~/.claude/skills write surface, not tested) — prefer the Codex form when installing ruflo.
• Network: codeload direct verified 1.7s (works on mainland and abroad), generally no mirror needed.
• Write surface: ~/.codex/skills/superpowers/ (plain file copy; no dependencies, no registration, no background process).

Daily usage

Startup and entry

No startup; skills are auto-triggered by the Agent as needed (decided by the SKILL.md description).

Common operations

Operation 1: Confirm installed skills

ls ~/.codex/skills/superpowers

Expected output: 14 个技能目录（brainstorming / test-driven-development / systematic-debugging / subagent-driven-development 等） Operation 2: Update to the latest (re-download and overwrite)

curl -sL -o /tmp/superpowers.tar.gz https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0 && rm -rf /tmp/superpowers-src && mkdir -p /tmp/superpowers-src && tar xzf /tmp/superpowers.tar.gz -C /tmp/superpowers-src --strip-components=1 && cp -r /tmp/superpowers-src/skills ~/.codex/skills/superpowers && echo "updated: OK"

Expected output: updated: OK Operation 3: Check whether the Claude form was installed

ls ~/.claude/skills/superpowers 2>/dev/null || echo "未安装 Claude 形态"

Expected output: 目录列表或未安装提示

Data and directories

• Skill directory: ~/.codex/skills/superpowers/ (Codex form);
• Claude form: ~/.claude/skills/superpowers or plugin registration.

Uninstall & cleanup

note: pure-file skill package — deleting the skill directory is zero-residue; the marketplace one-click uninstall runs it automatically

rm -rf ~/.codex/skills/superpowers
test ! -d ~/.codex/skills/superpowers && echo "superpowers removed: OK" || echo "残留: superpowers 仍存在"

Expected output: superpowers removed: OK Manual checklist (if you installed other forms):

• ~/.claude/skills/superpowers (manual copy form for Claude Code)
• Claude Code /plugins installed plugins (use /plugin uninstall superpowers)
• Other harnesses (Cursor/Gemini/Copilot etc.): remove via that platform's plugin management

Dependency warnings

• Version: [6.3.0, 6.3.0] locked (verified collection version; install commands pin the tag, no drift).
• Environment: no runtime requirements; the Codex form needs ~/.codex/skills writable.
• Network: codeload direct verified 1.7s (works on mainland and abroad).
• Write surface: ~/.codex/skills/superpowers/ (plain file copy; reinstalling overwrites the same-named directory).
• Co-install: judged possible-compatible with omc/agt/deepcode (no shared write surface); judged possible-conflict with ruflo (Claude form shares the ~/.claude/skills write surface, not tested) — prefer the Codex form when installing ruflo.

FAQ

• Q: Anything to configure after install? A: No. Skills are auto-triggered by the Agent as needed (decided by the SKILL.md description), no config file.
• Q: Will it affect my existing skills? A: superpowers skill subdirectory names are unique (e.g. brainstorming); if another skill set has a same-named skill, the later install overwrites (same-directory write surface) — check existing skill names under ~/.codex/skills first.
• Q: Why did my Agent's behavior change? A: That's expected — superpowers is a methodology framework (design before code, TDD, subagent-driven) and changes how the Agent works.
• Q: Updates are fast — how is the version locked? A: this entry locks 6.3.0 (manifest version_range single version); install commands pin the tag, no drift.
• Q: Can it coexist with other plugins? A: possible-compatible with omc/agt/deepcode (no shared write surface); possible-conflict with ruflo (Claude form shares the ~/.claude/skills write surface, not tested) — prefer the Codex form when installing ruflo.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel (usage-report template); project issues go to the author's repository.