# File Structure for a Superpowers Skill: Complete Guide to the skills/ Directory Layout

> Learn the Superpowers skill file structure. Discover the required SKILL.md format for metadata, checklists, and workflows within the skills/ directory.

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

---

**Every Superpowers skill resides in a dedicated subdirectory under `skills/` and must contain a [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) file with YAML front-matter defining the skill's metadata, checklist, and workflow.**

The **Superpowers** repository by `obra` organizes reusable automation skills through a strict directory convention. Understanding the file structure for a Superpowers skill is essential for contributing new capabilities or debugging existing ones, as the engine relies on this layout to discover and load functionality at runtime.

## The skills/ Directory Layout

All skills are stored as **sibling directories** under the top-level `skills/` folder. There is no deeper nesting—each skill occupies exactly one directory level below `skills/`, and the directory name itself serves as the skill's identifier.

The engine enforces a flat hierarchy to ensure predictable discovery. When [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) walks the file tree, it expects to find immediate subdirectories of `skills/`, each containing the mandatory definition file.

### Required Files: The SKILL.md Contract

Every skill directory must contain a file named exactly [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md). This file serves as the **authoritative contract** between the skill author and the Superpowers engine.

[`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) uses **YAML front-matter** to declare metadata followed by markdown content for documentation. The front-matter typically includes:

- `name`: The canonical skill identifier (usually matches the directory name)
- `description`: A concise explanation of the skill's purpose
- `checklist`: An array of steps or validation criteria
- `flow`: Mermaid or textual diagram data representing the workflow

The engine parses this file using the `gray-matter` library, separating the YAML metadata from the markdown body for runtime consumption.

### Optional Assets and Helper Files

Beyond the mandatory [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md), a skill directory may contain **supplementary assets** that extend its functionality. The engine treats these as opaque resources—the skill's logic or documentation can reference them by relative path.

Common supplementary file types include:

- **Markdown guides**: Additional documentation for complex workflows (e.g., [`testing-anti-patterns.md`](https://github.com/obra/superpowers/blob/main/testing-anti-patterns.md) in `skills/test-driven-development/`)
- **Shell scripts**: Executable helpers for environment setup or task automation (e.g., [`find-polluter.sh`](https://github.com/obra/superpowers/blob/main/find-polluter.sh) in `skills/systematic-debugging/`)
- **JavaScript utilities**: Node.js scripts for rendering diagrams or processing data (e.g., [`render-graphs.js`](https://github.com/obra/superpowers/blob/main/render-graphs.js) in `skills/writing-skills/`)
- **Prompt files**: Specialized markdown files containing LLM prompts for sub-agent coordination (e.g., [`spec-reviewer-prompt.md`](https://github.com/obra/superpowers/blob/main/spec-reviewer-prompt.md) and [`implementer-prompt.md`](https://github.com/obra/superpowers/blob/main/implementer-prompt.md) in `skills/subagent-driven-development/`)

The presence of these files does not affect the engine's discovery mechanism, but they enable rich, multi-step automation workflows.

## How the Superpowers Engine Discovers Skills

The runtime discovery logic is implemented in **[`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js)**. This module walks the `skills/` directory tree, identifies valid skill folders, and registers them for use.

The discovery process follows these steps:

1. **Directory traversal**: The engine reads immediate subdirectories of `skills/`
2. **Validation**: Each directory is checked for the presence of [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md)
3. **Parsing**: Valid [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) files are processed using `gray-matter` to extract YAML metadata and markdown content
4. **Registration**: The parsed skill object is added to the runtime registry, keyed by the skill name

This flat structure ensures that skill lookup is **O(1)** by directory name and prevents naming collisions through the filesystem's natural constraints.

### Programmatically Loading a Skill

You can interact with the skill system programmatically using the core loader. The following example demonstrates how to parse a skill definition manually:

```javascript
// Simplified excerpt from lib/skills-core.js
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 allows external tools to validate skill definitions or generate documentation without executing the full Superpowers runtime.

### Referencing Skills in Plan Files

When authoring automation plans, you reference skills by their directory name. The engine resolves these references to the corresponding [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) files:

```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 the **test-driven-development** skill during implementation

```

During execution, the system locates [`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/test-driven-development/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/test-driven-development/SKILL.md) to retrieve the checklists and workflow definitions.

## Real-World Skill Structure Examples

The repository contains diverse skill implementations that demonstrate how the file structure scales from simple checklists to complex multi-agent workflows.

### Simple Skills: brainstorming

The `skills/brainstorming/` directory contains only the essential file:

```

skills/brainstorming/
└── SKILL.md

```

This skill defines a lightweight creative process using only the YAML front-matter checklist and markdown documentation, requiring no external scripts or prompts.

### Skills with Prompt Files: subagent-driven-development

Complex coordination skills require additional prompt definitions:

```

skills/subagent-driven-development/
├── SKILL.md
├── spec-reviewer-prompt.md
├── implementer-prompt.md
└── [additional prompt files]

```

The [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) references these prompt files by relative path when orchestrating sub-agents, allowing the skill to maintain clean separation between workflow logic and prompt engineering.

### Skills with Helper Scripts: systematic-debugging

Some skills bundle executable tools for environment interaction:

```

skills/systematic-debugging/
├── SKILL.md
├── find-polluter.sh
└── condition-based-waiting-example.ts

```

The [`find-polluter.sh`](https://github.com/obra/superpowers/blob/main/find-polluter.sh) script assists in identifying test pollution, while the TypeScript example demonstrates implementation patterns. The [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) documents when and how to invoke these resources.

### Meta-Skills: writing-skills

The `writing-skills` skill demonstrates how to create documentation for the system itself:

```

skills/writing-skills/
├── SKILL.md
├── render-graphs.js
├── graphviz-conventions.dot
└── [docs and examples directories]

```

This skill includes JavaScript utilities for rendering workflow diagrams and Graphviz configuration files for consistent visual notation, illustrating how sophisticated tooling can be packaged within the standard skill structure.

## Summary

- **Every skill lives under `skills/`** as a sibling directory with no deeper nesting, ensuring predictable discovery by the engine.
- **[`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) is mandatory** in each skill directory and contains YAML front-matter defining metadata, checklists, and workflow diagrams.
- **Supplementary assets are optional** and can include shell scripts, JavaScript utilities, prompt files, or example code referenced by the skill.
- **Discovery is handled by [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js)**, which walks the `skills/` tree, parses [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) files using `gray-matter`, and registers them for runtime use.

## Frequently Asked Questions

### What is the minimum required file for a Superpowers skill?

The only mandatory file is **[`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md)** placed directly inside a subdirectory of `skills/`. This file must contain valid YAML front-matter that defines at minimum the skill's name and description. Without this file, the engine in [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) will not recognize the directory as a valid skill.

### Can I nest skill directories deeper than one level under skills/?

No. The Superpowers engine expects a **flat hierarchy** where all skill directories are immediate children of `skills/`. The discovery logic in [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) walks only the top level of the `skills/` directory, so nested directories would be ignored by the runtime loader.

### How does the Superpowers engine parse the SKILL.md file?

The engine uses the **`gray-matter`** library to parse [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md). It reads the file as UTF-8, extracts the YAML front-matter into a metadata object, and treats the remaining content as the markdown body. This parsed structure is then registered in the runtime skill registry, making the checklist and workflow data available for execution.

### What types of supplementary files can a skill include?

A skill can bundle any file type needed for its workflow, including **shell scripts** (like [`find-polluter.sh`](https://github.com/obra/superpowers/blob/main/find-polluter.sh)), **JavaScript utilities** (like [`render-graphs.js`](https://github.com/obra/superpowers/blob/main/render-graphs.js)), **prompt markdown files** (like [`spec-reviewer-prompt.md`](https://github.com/obra/superpowers/blob/main/spec-reviewer-prompt.md)), **example code** (like [`condition-based-waiting-example.ts`](https://github.com/obra/superpowers/blob/main/condition-based-waiting-example.ts)), and **configuration files** (like `graphviz-conventions.dot`). The engine treats these as opaque assets referenced by the skill's documentation or execution logic.