Skip to main content

​
What Are Skills?

Superpowers is built on a skills system - a collection of composable, reusable workflows that guide your coding agent through systematic software development. Each skill is a specialized set of instructions stored in a SKILL.md file that defines:
  • When the skill should be used (via frontmatter description)
  • What the skill does (workflow steps and processes)
  • How to execute the skill (detailed instructions and checklists)
Skills are mandatory workflows, not suggestions. When a skill applies to a task, the agent must use it - no exceptions.

​
How Skills Are Triggered

Skills activate automatically based on the context of what you’re asking. The agent checks for relevant skills before responding to any request.

​
Automatic Skill Detection

From skills/using-superpowers/SKILL.md:23-24: 
Invoke relevant or requested skills BEFORE any response or action. 
Even a 1% chance a skill might apply means that you should invoke the skill to check.
The skill system uses YAML frontmatter to determine when each skill applies: 
---
name: brainstorming
description: "You MUST use this before any creative work - creating features, 
             building components, adding functionality, or modifying behavior."
---

​
Skill Loading Architecture

From lib/skills-core.js:15-52, the system extracts skill metadata through frontmatter parsing:
1

Frontmatter Extraction

The extractFrontmatter() function reads the YAML header from each SKILL.md file to identify the skill’s name and when it should be triggered.
2

Skill Discovery

The findSkillsInDir() function recursively searches directories up to 3 levels deep, finding all SKILL.md files and building a skill registry.
3

Skill Resolution

The resolveSkillPath() function handles skill shadowing - personal skills can override built-in Superpowers skills by name.
4

Content Loading

The stripFrontmatter() function removes YAML metadata before presenting skill content to the agent.

​
Skill Types

Skills fall into several categories:

Testing

  • test-driven-development - Enforces RED-GREEN-REFACTOR cycle
  • verification-before-completion - Ensures fixes are validated

Debugging

  • systematic-debugging - 4-phase root cause analysis
  • Includes techniques for root-cause tracing and defense-in-depth

Collaboration

  • brainstorming - Socratic design refinement
  • writing-plans - Detailed implementation plans
  • executing-plans - Batch execution with checkpoints
  • dispatching-parallel-agents - Concurrent workflows

Code Quality

  • requesting-code-review - Pre-review checklist
  • receiving-code-review - Responding to feedback
  • subagent-driven-development - Fast iteration with two-stage review

Git Workflow

  • using-git-worktrees - Parallel development branches
  • finishing-a-development-branch - Merge/PR decision workflow

Meta

  • writing-skills - Create new skills following best practices
  • using-superpowers - Introduction to the skills system

​
How Skills Compose

Skills don’t operate in isolation - they orchestrate each other to create complete workflows.

​
Skill Orchestration Example

When you ask to build a feature, here’s how skills compose:

​
Skill Priority Rules

From skills/using-superpowers/SKILL.md:75-83:
When multiple skills could apply, use this order:
  1. Process skills first (brainstorming, debugging) - these determine HOW to approach the task
  2. Implementation skills second (frontend-design, mcp-builder) - these guide execution

​
Rigid vs. Flexible Skills

From skills/using-superpowers/SKILL.md:86-91:
  • Rigid skills (TDD, debugging): Follow exactly. Don’t adapt away discipline.
  • Flexible skills (patterns): Adapt principles to context.
The skill itself tells you which type it is.

​
Skill Shadowing

You can override built-in Superpowers skills with personal versions. From lib/skills-core.js:100-139:
1

Personal Skills Take Priority

If a skill exists in your personal skills directory, it shadows the Superpowers version.
2

Explicit Namespace

Use superpowers:skill-name to force using the built-in version even if a personal version exists.
3

Resolution Order

  1. Personal skills directory (unless superpowers: prefix)
  2. Superpowers skills directory

​
Red Flags to Avoid

From skills/using-superpowers/SKILL.md:56-73, these thoughts mean you’re rationalizing away the skill system:
ThoughtReality
”This is just a simple question”Questions are tasks. Check for skills.
”I need more context first”Skill check comes BEFORE clarifying questions.
”Let me explore the codebase first”Skills tell you HOW to explore. Check first.
”This doesn’t need a formal skill”If a skill exists, use it.
”I remember this skill”Skills evolve. Read current version.
”The skill is overkill”Simple things become complex. Use it.
”I’ll just do this one thing first”Check BEFORE doing anything.
If you think there’s even a 1% chance a skill might apply, you MUST invoke it. This is not negotiable.

​
Key Principles

Mandatory, Not Optional

Skills are enforced workflows. When a skill applies, the agent must use it.

Check Before Acting

Skill check happens BEFORE any response, including clarifying questions.

Composable by Design

Skills invoke other skills to create complete workflows.

Extensible

Create custom skills and override built-in ones.

​
Next Steps

Workflow

Learn the complete Superpowers workflow from brainstorming to deployment

Philosophy

Understand the four core principles that drive Superpowers

Build docs developers (and LLMs) love

Get started for freeTalk to us