How to Find Skills in the Superpowers Project Directory

You can find skills in the Superpowers project by browsing the top-level skills/ directory, searching for markdown files containing the name: header, or inspecting the dynamic loader in lib/skills-core.js.

The Superpowers project (obra/superpowers) organizes its agent workflow capabilities into modular, reusable units called skills. These skills are stored as structured markdown files within the repository. Understanding how to locate and identify these skills is essential for customizing behavior, debugging workflows, or extending the system.

Where Skills Are Stored in the Superpowers Repository

The skills/ Directory Structure

All skills reside in the top-level skills/ directory. Each skill occupies its own sub-directory, with the folder structure mirroring the skill taxonomy. Common categories include:

• brainstorming/ – Creative ideation workflows
• systematic-debugging/ – Structured troubleshooting processes
• using-superpowers/ – Meta-skills governing the agent's own operation

Within each sub-directory, the actual skill definition typically lives in a file named SKILL.md or similar markdown files.

Skill File Format and Headers

Every skill file follows a standard markdown format with a YAML frontmatter header:

---
name: brainstorming
description: Generate creative ideas through structured thinking
---

The name: field serves as the unique identifier for the skill. The runtime uses this header to register and reference the skill during execution.

Methods to Find Skills in the Superpowers Project Directory

Browse the Directory Tree

The simplest approach is to explore the skills/ directory structure directly. Use the tree command to visualize the hierarchy:

tree -d -L 2 ./skills

This reveals the categorical organization, showing folders like brainstorming, systematic-debugging, and using-superpowers.

Search for Skill Definitions with Grep

To locate all skill definitions programmatically, search for the name: header across all markdown files:

grep -R "^name:" -n ./skills/*.md

This command outputs the file path, line number, and skill name for every skill definition, allowing you to quickly inventory available capabilities.

Inspect the Core Loader Logic

The runtime discovers skills dynamically through the core loader implemented in lib/skills-core.js. This module uses Node.js filesystem APIs to scan the skills/ directory:

• fs.readdirSync – Enumerates files and directories
• path.join – Constructs platform-independent file paths

Examining this file reveals exactly how the system identifies valid skill files and parses their metadata headers.

Programmatically Listing Skills

You can replicate the loader's behavior to generate a skill inventory from your own scripts:

const fs = require('fs');
const path = require('path');

const skillDir = path.join(__dirname, 'skills');

const skillFiles = fs.readdirSync(skillDir, { withFileTypes: true })
  .filter(e => e.isFile() && e.name.endsWith('.md'))
  .map(e => e.name);

skillFiles.forEach(f => {
  const content = fs.readFileSync(path.join(skillDir, f), 'utf8');
  const nameMatch = content.match(/^name:\s*(.+)$/m);
  if (nameMatch) {
    console.log(`${nameMatch[1]} → ${f}`);
  }
});

This script iterates through the skills/ directory, parses the name: header from each markdown file, and maps skill identifiers to their source files.

Summary

• Skills reside in the top-level skills/ directory, with each skill in its own sub-folder.
• Skill files are markdown documents containing a YAML header with name: and description: fields.
• Use tree, grep, or file system utilities to browse and search the skill taxonomy.
• The runtime loader in lib/skills-core.js dynamically discovers skills using fs.readdirSync and parses their metadata.

Frequently Asked Questions

What is the standard format for a Superpowers skill file?

A Superpowers skill file is a markdown document with a YAML frontmatter header containing at minimum a name: field and a description: field, enclosed between triple dashes. The remainder of the file typically contains the skill's workflow steps, checklists, or flow diagrams.

How does the Superpowers runtime load skills dynamically?

The runtime uses the module at lib/skills-core.js to scan the skills/ directory at startup. It calls fs.readdirSync to enumerate markdown files, then reads and parses each file's YAML header to extract the skill name and metadata, registering each skill for use by the agent.

Where is the skill loader implemented in the source code?

The skill loader logic is implemented in lib/skills-core.js. This file contains the core functionality for filesystem traversal, file reading, and YAML header parsing that enables the dynamic discovery and registration of skills within the Superpowers framework.

Can I create custom skills in the Superpowers project?

Yes, you can create custom skills by adding new markdown files to the skills/ directory or creating sub-directories for organizational purposes. Each custom skill must include the standard YAML header with a unique name: field. The runtime will automatically discover and load your custom skills on the next startup.

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