This page explains the fundamental concepts that underpin the Superpowers system: what skills are, how they are structured, and the mandatory protocols that ensure AI agents follow them across various platforms.
Skills are reusable, modular units of AI guidance that provide structured workflows for coding agents. Unlike static prompts, skills are dynamic instructions that agents discover and invoke via specific tools based on the current task README.md3-5 They represent the core logic of the Superpowers methodology, transforming an AI from a simple code generator into a disciplined engineering partner README.md16-26
Every skill is defined in a SKILL.md file within a dedicated directory README.md181-182 They follow a specific format that combines metadata for discovery and content for execution.
Part 1: YAML Frontmatter The frontmatter contains the skill's identity and its "trigger" description, which the agent uses to match the current context skills/using-superpowers/SKILL.md1-4
Part 2: Markdown Content The body of the skill contains the actual instructions, often including:
Sources: skills/using-superpowers/SKILL.md1-4 skills/using-superpowers/SKILL.md18-25 skills/using-superpowers/SKILL.md33-51 skills/using-superpowers/SKILL.md60-63 README.md181-182
While skills are written using Claude Code tool names (like Skill, Task, and TodoWrite), they are designed to be cross-platform. The system maps these to native equivalents on other platforms skills/using-superpowers/SKILL.md52-59 For instance, Pi uses a specialized extension to map these to its native read, write, and bash tools pi/extensions/superpowers.ts88-97
| Claude Code Tool | Pi Equivalent | Codex Equivalent |
|---|---|---|
Skill | Native Skill system / read | references/codex-tools.md |
TodoWrite | TODO.md / task tool | Native plan tracking |
Task | subagent (if available) | spawn_agent |
Read/Write/Edit | read/write/edit | Native file tools |
Sources: skills/using-superpowers/SKILL.md52-59 .pi/extensions/superpowers.ts88-97 tests/pi/test-pi-extension.mjs121-128
For details, see What Are Skills.
Superpowers is built on a "Mandatory, not Suggested" philosophy. This is enforced by the using-superpowers meta-skill, which establishes how to find and use skills skills/using-superpowers/SKILL.md2-3
The system enforces a strict discipline: if there is even a 1% chance a skill might apply to the current task, the agent must invoke the skill skills/using-superpowers/SKILL.md10-16 This check must happen before any response, including clarifying questions or exploring the codebase skills/using-superpowers/SKILL.md18-20
To ensure the user remains in control, Superpowers follows a strict priority:
CLAUDE.md, AGENTS.md, GEMINI.md, direct requests) — Highest skills/using-superpowers/SKILL.md60-62Sources: skills/using-superpowers/SKILL.md10-20 skills/using-superpowers/SKILL.md60-63
For details, see The Mandatory Skill Check Protocol.
Agents do not "know" all skills at once. Instead, they use a discovery mechanism to find the right tool for the job.
When an agent receives a message, it follows this logic:
Skill Discovery and Invocation Logic
Sources: skills/using-superpowers/SKILL.md10-25 .pi/extensions/superpowers.ts16-21 tests/pi/test-pi-extension.mjs63-70
For details, see Finding and Invoking Skills.
When multiple skills apply, the system follows a specific resolution order to prevent conflicting instructions and ensure process discipline.
If multiple core skills apply, agents are instructed to prioritize Process skills (like brainstorming or systematic-debugging) over Implementation skills. This ensures the "How" is decided before the "What" is executed skills/using-superpowers/SKILL.md26-32
Workflow Tier Hierarchy
Sources: skills/using-superpowers/SKILL.md26-32 README.md188-203
For details, see Skill Priority and Overriding.