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

> Explore the Superpowers skills file structure. Learn how each skill in the obra/superpowers repository uses the SKILL.md file for metadata. Unlock efficient development.

- Repository: [Jesse Vincent/superpowers](https://github.com/obra/superpowers)
- Tags: how-to-guide
- Published: 2026-02-15

---

**Every reusable skill in the Superpowers framework resides under the top-level `skills/` directory, with each skill defined by a mandatory [`SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md) defines a process-oriented skill with a structured checklist, while [`skills/systematic-debugging/SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/SKILL.md):

- **Markdown guides**: Reference documents like [`skills/requesting-code-review/code-reviewer.md`](https://github.com/obra/superpowers/blob/main/skills/requesting-code-review/code-reviewer.md) or [`skills/test-driven-development/testing-anti-patterns.md`](https://github.com/obra/superpowers/blob/main/skills/test-driven-development/testing-anti-patterns.md)
- **Shell scripts**: Executable helpers such as [`skills/systematic-debugging/find-polluter.sh`](https://github.com/obra/superpowers/blob/main/skills/systematic-debugging/find-polluter.sh)
- **JavaScript utilities**: Build tools like [`skills/writing-skills/render-graphs.js`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/spec-reviewer-prompt.md), [`implementer-prompt.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js)**. This module walks the `skills/` directory tree, parses each [`SKILL.md`](https://github.com/obra/superpowers/blob/main/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`:

```javascript
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`](https://github.com/obra/superpowers/blob/main/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:

```markdown

# 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`](https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md), [`skills/writing-plans/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md), and [`skills/subagent-driven-development/SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) module to walk the `skills/` directory tree at startup. It reads each subdirectory, validates the presence of [`SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/testing-anti-patterns.md) or [`code-reviewer.md`](https://github.com/obra/superpowers/blob/main/code-reviewer.md)), executable shell scripts (like [`find-polluter.sh`](https://github.com/obra/superpowers/blob/main/find-polluter.sh)), JavaScript utilities (such as [`render-graphs.js`](https://github.com/obra/superpowers/blob/main/render-graphs.js)), and prompt templates for subagent coordination (like [`spec-reviewer-prompt.md`](https://github.com/obra/superpowers/blob/main/spec-reviewer-prompt.md)). These assets are stored alongside [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) in the skill's directory but are not required for the skill to function.