# Where to Find Core Skill Management Utilities in the Superpowers Repository

> Find core skill management utilities in the Superpowers repository within lib/skills-core.js. Discover helpers for skill discovery, parsing, and resolution.

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

---

**The core skill management utilities in the Superpowers repository are centralized in the [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) module, which implements all low-level helpers for skill discovery, parsing, and resolution.**

The `obra/superpowers` repository implements a modular skill system that allows users to extend functionality through declarative skill definitions. Understanding where the **core skill management utilities** reside is essential for developers who want to customize skill discovery, implement shadowing logic, or build tooling around the Superpowers ecosystem.

## Location of the Core Skill Management Module

All skill management utilities live in **[`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js)**. This module serves as the single source of truth for discovering, parsing, and resolving skill definitions across the repository. It handles the low-level operations that enable the runtime to load and execute skills from both the built-in `skills/` directory and user-defined locations.

The module exports several key functions that work together to provide a complete skill management pipeline:

- **`extractFrontmatter`** – Parses YAML front-matter from [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) files to extract metadata
- **`findSkillsInDir`** – Recursively scans directories for skill definitions
- **`resolveSkillPath`** – Maps skill names to concrete file system locations with shadowing support
- **`stripFrontmatter`** – Removes YAML headers to expose raw skill content
- **`checkForUpdates`** – Validates repository state against upstream changes

## Key Skill Management Functions

### Extracting Skill Metadata with extractFrontmatter

The **`extractFrontmatter`** function reads a skill's [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) front-matter to obtain its name and description. Located at lines 5-15 in [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js), this utility uses a regex-based parser to isolate YAML headers from markdown content.

This function enables the UI to display skill names and descriptions automatically without executing the skill logic.

### Discovering Available Skills with findSkillsInDir

The **`findSkillsInDir`** function (lines 54-97) recursively scans a directory for [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) files, building a catalog of available skills. It returns an array of skill objects containing metadata and file paths.

This utility powers skill discovery features, allowing the system to build lists of both core and user-defined capabilities.

### Resolving Skill Paths with Shadowing Logic

The **`resolveSkillPath`** function (lines 98-140) implements the critical shadowing mechanism that allows personal skills to override built-in ones. It resolves a requested skill name to the concrete file system location, checking `~/.superpowers/skills` before falling back to the repository's `skills/` directory.

This function ensures that user customizations take precedence over default Superpowers-provided skills.

### Processing Skill Content

The **`stripFrontmatter`** function (lines 72-88) removes the YAML front-matter from a skill file so the raw content can be processed by an LLM or other consumers. This is essential when feeding skill definitions to language models that should only see the instructional content, not the metadata headers.

## Practical Examples: Using the Core Skill Utilities

### Listing All Available Skills

To discover both built-in and personal skills programmatically, combine `findSkillsInDir` with path resolution:

```javascript
import { findSkillsInDir } from './lib/skills-core.js';
import path from 'path';

// Paths are relative to the repo root.
const superpowersDir = path.resolve('skills');               // built‑in skills
const personalDir   = path.resolve(process.env.HOME, '.superpowers', 'skills'); // optional user dir

const builtIn  = findSkillsInDir(superpowersDir, 'superpowers');
const personal = personalDir ? findSkillsInDir(personalDir, 'personal') : [];

const allSkills = [...personal, ...builtIn];
console.log('Discovered skills:', allSkills.map(s => s.name));

```

### Resolving a Skill to Its File Location

When you need to locate the actual [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) file for a specific capability:

```javascript
import { resolveSkillPath } from './lib/skills-core.js';
import path from 'path';

const superpowersDir = path.resolve('skills');
const personalDir   = path.resolve(process.env.HOME, '.superpowers', 'skills');

const result = resolveSkillPath('using-superpowers', superpowersDir, personalDir);
if (result) {
  console.log(`Skill file located at: ${result.skillFile}`);
  console.log(`Source type: ${result.sourceType}`);
} else {
  console.error('Skill not found');
}

```

### Preparing Skill Content for LLM Processing

To strip metadata before feeding skill instructions to a language model:

```javascript
import fs from 'fs';
import { stripFrontmatter } from './lib/skills-core.js';

const skillPath = 'skills/using-superpowers/SKILL.md';
const raw = fs.readFileSync(skillPath, 'utf8');
const body = stripFrontmatter(raw);
console.log(body); // pure markdown without the YAML header

```

## Summary

- The **core skill management utilities** reside exclusively in **[`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js)** within the `obra/superpowers` repository.
- This module provides **five primary functions**: `extractFrontmatter`, `findSkillsInDir`, `resolveSkillPath`, `stripFrontmatter`, and `checkForUpdates`.
- **Skill shadowing** is implemented in `resolveSkillPath`, allowing personal skills in `~/.superpowers/skills` to override built-in definitions.
- The utilities enable **automatic skill discovery** by scanning for [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) files and extracting YAML front-matter metadata.
- Raw skill content can be isolated using `stripFrontmatter` for processing by LLMs or other consumers.

## Frequently Asked Questions

### Where are the core skill management utilities located in the Superpowers repository?

The core skill management utilities are centralized in **[`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js)**. This single module exports all low-level helpers for discovering, parsing, and resolving skill definitions across the codebase, making it the primary entry point for skill-related operations.

### How does Superpowers handle skill shadowing and overrides?

Superpowers implements skill shadowing through the **`resolveSkillPath`** function in [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js). When resolving a skill name, the utility first checks the personal skills directory at `~/.superpowers/skills` before falling back to the built-in `skills/` directory, ensuring user customizations take precedence over default definitions.

### What is the purpose of the extractFrontmatter function?

The **`extractFrontmatter`** function parses the YAML front-matter from [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) files to extract metadata such as the skill name and description. Located at lines 5-15 of [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js), this utility enables the UI and runtime to display skill information without executing the skill logic.

### How do I programmatically list all available skills in Superpowers?

To list all available skills, import the **`findSkillsInDir`** function from [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) and invoke it on both the built-in `skills/` directory and the optional personal directory at `~/.superpowers/skills`. This function recursively scans for [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) files and returns an array of skill objects containing metadata and file paths.