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

> Discover how SKILL.md frontmatter is stripped at runtime in the i-have-adhd repository. Learn about the regex that removes delimiters before parsing.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: internals
- Published: 2026-08-22

---

**TLDR: The [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) frontmatter is removed at runtime by a regular expression defined in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) file at the root of the skill directory begins with a YAML block:

```markdown
---
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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)** — the extension that acts as the bridge between the repository's skill files and the OpenCode runtime.

```typescript
// 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:

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

```

The flow is straightforward:

1. `readFile()` loads the raw [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) behaves identically to the source in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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:

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

```bash
opencode run i-have-adhd

```

## Key Files in the Repository

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

## Summary

- The [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) frontmatter is stripped at runtime using a single regex defined in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.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`](https://github.com/ayghri/i-have-adhd/blob/main/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.