# How to Find Skills in the Superpowers Project Directory

> Discover how to find skills in the Superpowers project directory. Explore the skills directory search markdown files or inspect the dynamic loader to locate them.

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

---

**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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/SKILL.md) or similar markdown files.

### Skill File Format and Headers

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

```markdown
---
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:

```bash
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:

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

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