Where to Find Core Skill Management Utilities in the Superpowers Repository

The core skill management utilities in the Superpowers repository are centralized in the 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. 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 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 front-matter to obtain its name and description. Located at lines 5-15 in 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 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:

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 file for a specific capability:

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:

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 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 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. 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. 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 files to extract metadata such as the skill name and description. Located at lines 5-15 of 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 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 files and returns an array of skill objects containing metadata and file paths.

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