How SKILL.md Frontmatter Is Stripped at Runtime in the i-have-adhd Repository

TLDR: The SKILL.md frontmatter is removed at runtime by a regular expression defined in extensions/i-have-adhd.ts that matches the opening and closing --- delimiters and replaces them with an empty string before the skill body is parsed.

The ayghri/i-have-adhd repository implements an ADHD coaching skill that can be loaded by multiple AI coding runtimes. Every skill definition starts with a YAML frontmatter block containing metadata, but that block must be removed before the actual skill instructions reach the processing pipeline. The repository solves this with a single, reusable regex defined in the extension's entry-point source file.

Why Frontmatter Must Be Stripped Before Processing

The SKILL.md file at the root of the skill directory begins with a YAML block:

---
name: i-have-adhd
description: Coaching skill for ADHD users
version: 1.0.0
---

# Actual Skill Instructions

This frontmatter block is essential for discovery and tooling, but it is not part of the skill's executable instructions. If it were passed to the runtime unchanged, the parser would misinterpret the YAML metadata as markdown content, corrupting the skill output. Stripping it is a mandatory step in the load sequence.

The Regex That Does the Stripping

The core logic lives in extensions/i-have-adhd.ts — the extension that acts as the bridge between the repository's skill files and the OpenCode runtime.

// extensions/i-have-adhd.ts
const FRONT_MATTER_REGEX = /^---[^\S\r\n]*\r?\n[\s\S]*?\r?\n---[^\S\r\n]*(?:\r?\n|$)/;

This regex matches:

• The opening --- at the very start of the file (^---)
• An optional trailing whitespace and a newline ([^\S\r\n]*\r?\n)
• Everything up to the closing delimiter using a lazy capture ([\s\S]*?\r?\n---)
• The final newline that follows the closing ---

Because the [\s\S]*? portion is lazy, the regex stops at the first occurrence of the closing ---, which is exactly correct for a well-formed frontmatter block.

The Runtime Stripping Logic in Detail

The stripping operation is performed right after the file is read from disk:

const rawSkill = await readFile(skillPath, "utf8");
const skillWithoutFrontMatter = rawSkill.replace(FRONT_MATTER_REGEX, "");

The flow is straightforward:

1. readFile() loads the raw SKILL.md content from the skill path.
2. String.replace() applies the regex, removing the frontmatter block entirely.
3. The cleaned markdown (containing only the actual skill rules) is passed to the skill-processing pipeline — for example, the Cursor skill loader that expects a clean instruction body.

This is why the mirrored copy in .cursor/skills/i-have-adhd/SKILL.md behaves identically to the source in skills/i-have-adhd/SKILL.md: both go through the same stripping logic whenever the runtime loads them.

Why Use a Repeated Regex Instead of a YAML Parser

The extension deliberately avoids pulling in a full YAML parser. The regex approach has three concrete advantages:

• Zero dependencies — no js-yaml or gray-matter package is required.
• Fast — a single String.replace call is faster than parsing and reserializing JSON/YAML.
• Predictable — the regex contract is explicit; any frontmatter that follows the --- convention is stripped uniformly.

The trade-off is that the regex expects a strict ----delimited format. Files with multiple --- separators inside the body could in theory confuse a naive lazy match, but for skill files in this repository, that pattern never occurs because the body is pure markdown.

Practical Implementation with Your Own Loader

If you want to apply the same technique outside this repository, you can replicate it with plain Node.js:

import { readFile } from "fs/promises";

async function loadSkill(path) {
  const raw = await readFile(path, "utf8");
  const clean = raw.replace(
    /^---[^\S\r\n]*\r?\n[\s\S]*?\r?\n---[^\S\r\n]*(?:\r?\n|$)/,
    ""
  );
  return clean; // now contains only the skill body
}

loadSkill("./skills/i-have-adhd/SKILL.md").then(console.log);

Or, if you are using the built-in OpenCode CLI, the stripping happens automatically:

opencode run i-have-adhd

Key Files in the Repository

File	Role	Link
extensions/i-have-adhd.ts	Implements the frontmatter-stripping regex used at runtime	View Source
skills/i-have-adhd/SKILL.md	Source of the skill definition that contains the frontmatter	View Source
.cursor/skills/i-have-adhd/SKILL.md	Mirror of the canonical skill (kept in sync)	View Source
AGENTS.md	Maps runtimes to their entry points (including the OpenCode loader)	View Source

Summary

• The SKILL.md frontmatter is stripped at runtime using a single regex defined in extensions/i-have-adhd.ts.
• The regex matches the opening ---, captures everything up to the closing ---, and removes it via String.replace.
• The cleaned markdown is sent down the skill pipeline, ensuring only the actual instructions reach the runtime.
• The same logic applies identically to .cursor/skills/i-have-adhd/SKILL.md because it is a mirror of the canonical source.
• The approach is dependency-free and fast, making it ideal for skill loaders that need to process multiple files quickly.

Frequently Asked Questions

Where exactly is the frontmatter-stripping code located?

The stripping logic lives in extensions/i-have-adhd.ts. It defines a FRONT_MATTER_REGEX constant and calls String.replace() on the raw file content to remove the frontmatter block before further processing.

Does the repository use a YAML parser to strip the frontmatter?

No. The repository uses a Python-compatible but pre-made regex approach with zero dependencies. The regex handles the --- delimited block directly, which is faster and simpler than pulling in a full YAML library.

What happens if the frontmatter is not stripped?

The runtime would interpret the YAML frontmatter block as markdown instructions, polluting the skill output. That's why the stripping is a mandatory step in the load sequence.

Can I reuse this technique in my own project?

Yes. Copy the regex from FRONT_MATTER_REGEX and call replace() on any markdown file containing --- delimiters. Just ensure your files follow the exact same frontmatter format.

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