Superpowers Skills File Structure: A Complete Guide to the obra/superpowers Repository

Every reusable skill in the Superpowers framework resides under the top-level skills/ directory, with each skill defined by a mandatory SKILL.md file containing YAML front-matter metadata.

The obra/superpowers repository implements a flat, discoverable file structure for its skill system. Understanding this layout is essential for contributing new capabilities or invoking existing skills within automated development plans.

Understanding the Superpowers Skills Directory Layout

All skills are siblings under the skills/ folder at the repository root. There is no deeper nesting beyond the individual skill directory, ensuring the discovery engine can traverse the tree efficiently.

The SKILL.md Convention

Every skill directory must contain a SKILL.md file. This file serves as the authoritative definition, containing:

• YAML front-matter with metadata fields (name, description, checklist, flow diagram references)
• Markdown body describing the skill's execution logic and prerequisites

For example, skills/brainstorming/SKILL.md defines a process-oriented skill with a structured checklist, while skills/systematic-debugging/SKILL.md includes diagnostic flow diagrams in its front-matter.

Supplementary Assets and Helper Files

Skills may include additional assets beyond the core SKILL.md:

• Markdown guides: Reference documents like skills/requesting-code-review/code-reviewer.md or skills/test-driven-development/testing-anti-patterns.md
• Shell scripts: Executable helpers such as skills/systematic-debugging/find-polluter.sh
• JavaScript utilities: Build tools like skills/writing-skills/render-graphs.js
• Configuration templates: Dotfiles like skills/writing-skills/graphviz-conventions.dot

The skills/subagent-driven-development/ directory demonstrates a complex skill that coordinates multiple prompt files (spec-reviewer-prompt.md, implementer-prompt.md) alongside its primary definition.

How Skills Are Discovered and Loaded

The core engine that discovers and registers skills lives in lib/skills-core.js. This module walks the skills/ directory tree, parses each SKILL.md file, and registers the skill for runtime use.

Loading a Skill Programmatically

You can load skill metadata and content using standard Node.js filesystem operations combined with a YAML front-matter parser like gray-matter:

import { readFileSync } from 'fs';
import matter from 'gray-matter';
import path from 'path';

function loadSkill(name) {
  const skillPath = path.join(__dirname, '..', 'skills', name, 'SKILL.md');
  const content = readFileSync(skillPath, 'utf8');
  const { data, content: body } = matter(content); // parses YAML front-matter
  return { meta: data, body };
}

// Load the brainstorming skill
const brainstorming = loadSkill('brainstorming');
console.log(brainstorming.meta.name);   // → "brainstorming"

This pattern mirrors the implementation in lib/skills-core.js, which the Superpowers engine uses to build the skill registry at startup.

Referencing Skills in Plan Files

When authoring a development plan, you invoke skills by name. The engine resolves these names to the corresponding skills/{name}/SKILL.md paths:

# My Feature Plan

- [ ] Use the **brainstorming** skill to explore the idea
- [ ] After approval, run the **writing-plans** skill to produce an implementation plan
- [ ] Execute development using **subagent-driven-development**

During execution, the system validates that skills/brainstorming/SKILL.md, skills/writing-plans/SKILL.md, and skills/subagent-driven-development/SKILL.md exist and contain valid metadata before invoking their checklists.

Summary

• Top-level skills/ directory: All skills are flat siblings under this folder with no nested subdirectories.
• Mandatory SKILL.md: Every skill requires this file with YAML front-matter defining metadata, checklists, and flow diagrams.
• Optional assets: Skills may include supplementary markdown guides, shell scripts, JavaScript utilities, or prompt templates.
• Discovery mechanism: lib/skills-core.js walks the skills/ tree, parses front-matter, and registers skills for runtime invocation.
• Plan integration: Skills are referenced by directory name in plan files, resolving to skills/{name}/SKILL.md.

Frequently Asked Questions

What is the purpose of the SKILL.md file?

The SKILL.md file serves as the canonical definition for a Superpowers skill. It contains YAML front-matter with structured metadata including the skill name, description, execution checklist, and flow diagram references. The markdown body provides human-readable documentation and implementation guidance. The lib/skills-core.js engine specifically looks for this filename when discovering and loading skills.

Can skills contain subdirectories?

No, the Superpowers file structure enforces a flat hierarchy. All skill directories are direct children of the skills/ folder with no nested subdirectories. While a skill directory may contain multiple files (such as helper scripts or markdown guides), it cannot contain further subdirectories. This design ensures the discovery engine in lib/skills-core.js can traverse the skill tree efficiently without recursive depth complexity.

How does the Superpowers engine locate skills at runtime?

The engine uses the lib/skills-core.js module to walk the skills/ directory tree at startup. It reads each subdirectory, validates the presence of SKILL.md, and parses the YAML front-matter using a library like gray-matter. The extracted metadata is registered in a runtime skill registry, allowing plan files to invoke skills by their directory name. This discovery process happens once during initialization, creating an in-memory map of all available capabilities.

What types of supplementary files can a skill include?

Skills may bundle various asset types to support their execution. Common supplementary files include markdown reference guides (such as testing-anti-patterns.md or code-reviewer.md), executable shell scripts (like find-polluter.sh), JavaScript utilities (such as render-graphs.js), and prompt templates for subagent coordination (like spec-reviewer-prompt.md). These assets are stored alongside SKILL.md in the skill's directory but are not required for the skill to function.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}