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

Every Superpowers skill resides in a dedicated subdirectory under skills/ and must contain a 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 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. This file serves as the authoritative contract between the skill author and the Superpowers engine.

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, 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 in skills/test-driven-development/)
• Shell scripts: Executable helpers for environment setup or task automation (e.g., find-polluter.sh in skills/systematic-debugging/)
• JavaScript utilities: Node.js scripts for rendering diagrams or processing data (e.g., 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 and 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. 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
3. Parsing: Valid 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:

// 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 files:

# 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, skills/writing-plans/SKILL.md, and 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 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 script assists in identifying test pollution, while the TypeScript example demonstrates implementation patterns. The 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 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, which walks the skills/ tree, parses 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 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 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 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. 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), JavaScript utilities (like render-graphs.js), prompt markdown files (like spec-reviewer-prompt.md), example code (like 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.

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