How to Strip YAML Frontmatter from Superpowers Skill Content

Use the stripFrontmatter function in lib/skills-core.js to remove YAML metadata blocks delimited by --- from Superpowers skill files, returning only the executable Markdown body.

When working with the obra/superpowers framework, skill definitions reside in SKILL.md files that combine YAML frontmatter with Markdown content. To execute or render these skills, you must strip YAML frontmatter from Superpowers skill content to isolate the functional Markdown body from the metadata configuration.

Understanding YAML Frontmatter in Superpowers

Superpowers skill files follow a standard format where metadata—such as skill name, description, and configuration parameters—lives between triple-dash delimiters at the file start. The actual skill implementation follows as standard Markdown. When the runtime loads these files, it needs to separate this metadata from the executable content while preserving the integrity of the body text.

The stripFrontmatter Implementation in lib/skills-core.js

The primary mechanism for removing frontmatter resides in the stripFrontmatter function within lib/skills-core.js (lines 78-99). This utility processes raw file content by line, tracking delimiter states to identify and exclude the YAML block while preserving everything else.

The function operates through a state machine approach:

• It splits the input content by newline characters
• It tracks whether the parser is currently inside a frontmatter block using the inFrontmatter flag
• It identifies opening and closing --- delimiters
• It collects only lines that fall outside the frontmatter boundaries
• It joins the retained lines and trims trailing whitespace

Source Code Reference

// Source: lib/skills-core.js#L78-L99
function stripFrontmatter(content) {
    const lines = content.split('\n');
    let inFrontmatter = false;
    let frontmatterEnded = false;
    const contentLines = [];

    for (const line of lines) {
        if (line.trim() === '---') {
            if (inFrontmatter) {
                frontmatterEnded = true;
                continue;
            }
            inFrontmatter = true;
            continue;
        }

        if (frontmatterEnded || !inFrontmatter) {
            contentLines.push(line);
        }
    }

    return contentLines.join('\n').trim();
}

Practical Implementation Examples

When building custom loaders or processing skill files outside the standard runtime, you can import and utilize this utility directly from the core library.

Processing a Single Skill File

To manually strip frontmatter from a specific skill file:

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 markdownBody = stripFrontmatter(raw);
console.log(markdownBody);   // → only the skill’s Markdown content, no YAML block

Integrating with Custom Skill Loaders

When implementing a custom skill resolution system:

import { resolveSkillPath, stripFrontmatter } from '../lib/skills-core.js';
import fs from 'fs';

function loadSkill(skillName) {
  const resolved = resolveSkillPath(skillName,
                                   '/path/to/superpowers/skills',
                                   '/path/to/personal/skills');
  if (!resolved) throw new Error('Skill not found');

  const raw = fs.readFileSync(resolved.skillFile, 'utf8');
  return stripFrontmatter(raw);   // returns clean Markdown for execution
}

Visual Example of Transformation

Input file containing frontmatter:

---  
name: my-skill  
description: Demonstrates front-matter stripping  
---

# My Skill

This is the real content that will be processed.

After processing with stripFrontmatter:

# My Skill

This is the real content that will be processed.

How Superpowers Uses Frontmatter Stripping

The runtime applies this utility during the skill loading pipeline. In .opencode/plugins/superpowers.js, the system first extracts metadata from the frontmatter for initialization purposes, then passes the raw content through stripFrontmatter to isolate the executable Markdown body. This separation allows the runtime to access configuration data while passing only the relevant content to the execution engine.

Summary

• Superpowers skill files combine YAML frontmatter with Markdown content, separated by --- delimiters
• The stripFrontmatter function in lib/skills-core.js (lines 78-99) removes the YAML block using a line-by-line state machine
• The function returns only the Markdown body, trimming trailing whitespace
• Both manual processing and custom loaders can import this utility directly from the core library
• The Superpowers runtime uses this function in .opencode/plugins/superpowers.js to prepare skill content for execution

Frequently Asked Questions

What is the purpose of YAML frontmatter in Superpowers?

YAML frontmatter in Superpowers skill files stores metadata such as the skill name, description, version, and configuration parameters. This metadata is used by the runtime to identify, categorize, and initialize skills before executing the actual Markdown content.

Where is the stripFrontmatter function located?

The stripFrontmatter function is located in lib/skills-core.js at lines 78-99. This file contains core utilities for skill discovery, path resolution, and content processing within the Superpowers framework according to the source code.

Does stripFrontmatter handle malformed frontmatter?

The current implementation assumes well-formed frontmatter with matching opening and closing --- delimiters. If a file lacks proper delimiters, the function treats the entire content as Markdown body text and returns it unchanged, preventing data loss but not validating YAML syntax.

Can I use stripFrontmatter for non-skill files?

Yes, the stripFrontmatter function is a generic utility that processes any text content containing --- delimiters. You can import it from lib/skills-core.js to strip YAML frontmatter from any Markdown file, documentation, or content file that follows the same format, regardless of whether it is a Superpowers skill.

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