> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills System Overview

> Learn how Superpowers uses composable skills to enforce systematic development workflows

## 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)

<Info>
  Skills are **mandatory workflows, not suggestions**. When a skill applies to a task, the agent must use it - no exceptions.
</Info>

## 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:

```yaml theme={null}
---
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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="Skill Discovery">
    The `findSkillsInDir()` function recursively searches directories up to 3 levels deep, finding all `SKILL.md` files and building a skill registry.
  </Step>

  <Step title="Skill Resolution">
    The `resolveSkillPath()` function handles skill shadowing - personal skills can override built-in Superpowers skills by name.
  </Step>

  <Step title="Content Loading">
    The `stripFrontmatter()` function removes YAML metadata before presenting skill content to the agent.
  </Step>
</Steps>

## Skill Types

Skills fall into several categories:

<CardGroup cols={2}>
  <Card title="Testing" icon="flask">
    * **test-driven-development** - Enforces RED-GREEN-REFACTOR cycle
    * **verification-before-completion** - Ensures fixes are validated
  </Card>

  <Card title="Debugging" icon="bug">
    * **systematic-debugging** - 4-phase root cause analysis
    * Includes techniques for root-cause tracing and defense-in-depth
  </Card>

  <Card title="Collaboration" icon="users">
    * **brainstorming** - Socratic design refinement
    * **writing-plans** - Detailed implementation plans
    * **executing-plans** - Batch execution with checkpoints
    * **dispatching-parallel-agents** - Concurrent workflows
  </Card>

  <Card title="Code Quality" icon="code">
    * **requesting-code-review** - Pre-review checklist
    * **receiving-code-review** - Responding to feedback
    * **subagent-driven-development** - Fast iteration with two-stage review
  </Card>

  <Card title="Git Workflow" icon="git-alt">
    * **using-git-worktrees** - Parallel development branches
    * **finishing-a-development-branch** - Merge/PR decision workflow
  </Card>

  <Card title="Meta" icon="book">
    * **writing-skills** - Create new skills following best practices
    * **using-superpowers** - Introduction to the skills system
  </Card>
</CardGroup>

## 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:

```mermaid theme={null}
graph TD
    A[User: Build auth feature] --> B[brainstorming skill]
    B --> C[using-git-worktrees skill]
    C --> D[writing-plans skill]
    D --> E{Execution Choice}
    E -->|Same Session| F[subagent-driven-development]
    E -->|New Session| G[executing-plans]
    F --> H[test-driven-development]
    G --> H
    H --> I[requesting-code-review]
    I --> J[finishing-a-development-branch]
```

### Skill Priority Rules

From `skills/using-superpowers/SKILL.md:75-83`:

<Note>
  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
</Note>

### 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`:

<Steps>
  <Step title="Personal Skills Take Priority">
    If a skill exists in your personal skills directory, it shadows the Superpowers version.
  </Step>

  <Step title="Explicit Namespace">
    Use `superpowers:skill-name` to force using the built-in version even if a personal version exists.
  </Step>

  <Step title="Resolution Order">
    1. Personal skills directory (unless `superpowers:` prefix)
    2. Superpowers skills directory
  </Step>
</Steps>

## Red Flags to Avoid

From `skills/using-superpowers/SKILL.md:56-73`, these thoughts mean you're rationalizing away the skill system:

| Thought                             | Reality                                        |
| ----------------------------------- | ---------------------------------------------- |
| "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.                   |

<Warning>
  If you think there's even a 1% chance a skill might apply, you MUST invoke it. This is not negotiable.
</Warning>

## Key Principles

<CardGroup cols={2}>
  <Card title="Mandatory, Not Optional" icon="lock">
    Skills are enforced workflows. When a skill applies, the agent must use it.
  </Card>

  <Card title="Check Before Acting" icon="search">
    Skill check happens BEFORE any response, including clarifying questions.
  </Card>

  <Card title="Composable by Design" icon="puzzle-piece">
    Skills invoke other skills to create complete workflows.
  </Card>

  <Card title="Extensible" icon="plus">
    Create custom skills and override built-in ones.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Workflow" href="/concepts/workflow" icon="diagram-project">
    Learn the complete Superpowers workflow from brainstorming to deployment
  </Card>

  <Card title="Philosophy" href="/concepts/philosophy" icon="lightbulb">
    Understand the four core principles that drive Superpowers
  </Card>
</CardGroup>