Hand-Building a Skill Runtime: Scanning, Frontmatter Parsing, Injecting the System Prompt, Reading the Body on Demand

Scanning: find every folder containing a SKILL.md

The rule is one line: a directory containing a SKILL.md is a skill. No registry, no manifest, no compilation.

What is genuinely hard is the traversal itself. Three things must be handled.

A depth limit and a skip list. Recurse blindly in a real project and you will scan tens of thousands of directories, the overwhelming majority of them inside node_modules. Set a limit of four or five levels and keep a skip set holding out .git, node_modules, and build output. This is not an optimization but a question of usability — scanning sits on the session startup path, and two extra seconds is a cost paid every time.

Stop when you find one. Once a directory has a SKILL.md, do not drill further. Skills do not nest, and continuing only makes you try its references/ as another skill directory.

Multiple scopes and name collisions. At least two places must be scanned: project level and user level. As day two covered, the prevailing cross-client convention is project level beating user level, while Claude Code orders enterprise, personal, and project from high to low — the specific precedence follows whichever implementation you build, and what matters is fixing one and staying consistent rather than leaving it to chance.

How a collision is handled matters more than which direction it goes. The worst approach is silent discard: a user edits the skill in the project, restarts, and behavior has not changed at all, because what is in effect is the user-level copy. They will suspect the file did not save and suspect a client cache, and never think of a same-named copy somewhere else. So a shadowed skill must leave a warning, and it must print both paths — that log line is the first place to look when diagnosing this.

Parsing: how lenient should it be

SKILL.md's structure is extremely simple: a stretch of YAML between two triple-dash lines and body text for the rest. But you are parsing files other people wrote, and malformed input is the norm.

A key decision arises here: on encountering non-conforming content, do you refuse to load or load with degradation? The answer is lenient, with exactly one exception.

The only hard rejection is a missing description. Without it, this skill has no trigger surface in the discovery stage, will never be selected, and keeping it in the catalog merely wastes tokens. Skip that one outright and record an error-level diagnostic.

Everything else warns and still loads. A name that disagrees with the directory name, a name using capitals or underscores, a description over the limit — all affect quality without affecting whether the skill can be used. Your runtime is not a validator; the user installed this skill to get work done, not to pass a check.

The most common malformation is a bare colon in the YAML. A line like description: use when the user says: help me commit has a colon in the middle that makes a proper parser treat the line as invalid and throw out the entire file. The right fallback order is: try a full YAML parser first, and on failure drop back to a dumb read-by-line approach that extracts only the few scalar fields you recognize. That way a skill with mispunctuated text still works instead of disappearing entirely.

The code below is the piece of the runtime most worth reading closely: separating the frontmatter, then validating leniently by the rules above. Note that every continue means "record it and let it through."

export type Diagnostic = { level: 'warn' | 'error'; path: string; message: string }
export type Skill = { name: string; description: string; location: string; body: string }
 
const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/
 
export function splitFrontmatter(raw: string): { front: string; body: string } | null {
  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw)
  return m ? { front: m[1], body: m[2].trim() } : null
}
 
// The read-by-line fallback: used when the proper YAML parse fails, curing unquoted colons in values
function readField(front: string, key: string): string | undefined {
  const m = new RegExp(`^${key}:\\s*(.+)$`, 'm').exec(front)
  return m?.[1].trim().replace(/^["']|["']$/g, '')
}
 
export function parseSkill(location: string, dir: string, raw: string) {
  const diagnostics: Diagnostic[] = []
  const parts = splitFrontmatter(raw)
  if (!parts)
    return { skill: null, diagnostics: [{ level: 'error', path: location, message: 'no frontmatter' }] }
 
  const name = readField(parts.front, 'name') ?? dir
  const description = readField(parts.front, 'description')
  if (!description) {
    // The only hard rejection: no description means no trigger surface, so it could never be selected
    diagnostics.push({ level: 'error', path: location, message: 'missing description, skipping' })
    return { skill: null, diagnostics }
  }
  // The three below only warn and still load — that is lenient validation
  if (name !== dir)
    diagnostics.push({ level: 'warn', path: location, message: `name disagrees with the directory: ${name}` })
  if (!NAME_RE.test(name))
    diagnostics.push({ level: 'warn', path: location, message: `name breaks the naming rules` })
  if (description.length > 1024)
    diagnostics.push({ level: 'warn', path: location, message: 'description over the limit' })
 
  return { skill: { name, description, location, body: parts.body }, diagnostics }
}

import re
from dataclasses import dataclass
 
NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
FM_RE = re.compile(r"^---\r?\n(.*?)\r?\n---\r?\n?(.*)$", re.S)
 
 
@dataclass
class Skill:
    name: str
    description: str
    location: str
    body: str
 
 
def split_frontmatter(raw: str):
    m = FM_RE.match(raw)
    return (m.group(1), m.group(2).strip()) if m else None
 
 
def read_field(front: str, key: str):
    # The read-by-line fallback: used when the proper YAML parse fails, curing unquoted colons in values
    m = re.search(rf"^{key}:\s*(.+)$", front, re.M)
    return m.group(1).strip().strip("\"'") if m else None
 
 
def parse_skill(location: str, dirname: str, raw: str):
    diagnostics: list[dict] = []
    parts = split_frontmatter(raw)
    if parts is None:
        return None, [{"level": "error", "path": location, "message": "no frontmatter"}]
 
    front, body = parts
    name = read_field(front, "name") or dirname
    description = read_field(front, "description")
    if not description:
        # The only hard rejection: no description means no trigger surface, so it could never be selected
        diagnostics.append({"level": "error", "path": location, "message": "missing description, skipping"})
        return None, diagnostics
    # The three below only warn and still load — that is lenient validation
    if name != dirname:
        diagnostics.append(
            {"level": "warn", "path": location, "message": f"name disagrees with the directory: {name}"}
        )
    if not NAME_RE.match(name):
        diagnostics.append({"level": "warn", "path": location, "message": "name breaks the naming rules"})
    if len(description) > 1024:
        diagnostics.append({"level": "warn", "path": location, "message": "description over the limit"})
 
    return Skill(name, description, location, body), diagnostics

Disclosure: the catalog is the only thing you pay for every turn

The discovery stage's product is a catalog injected into the system prompt. It looks like this:

The following skills provide specialized instructions for particular tasks.
When a task matches a description, read the file at its location before continuing.
Relative paths inside a skill body resolve against that skill's directory.
<available_skills>
  <skill>
    <name>commit-message</name>
    <description>Use when the user is committing code or writing a commit message…</description>
    <location>.agents/skills/commit-message/SKILL.md</location>
  </skill>
</available_skills>

Three design points.

Each entry has only a name, a description, and a location. A body entering here cancels progressive disclosure — you would pay, every turn, for the full bodies of twenty skills, nineteen of them unrelated to the current task. The location cannot be omitted: the model needs it to know which file to read, and its parent directory is the base for resolving every relative path in the body.

Omit the whole section when there are no skills. Hand the model an empty list and it will only be confused, having spent a few dozen tokens on rules it cannot use.

Compute the catalog's cost and print it in the startup log. That is a very cheap and very useful habit. You will immediately see which skill's description runs too long — one description taking half the catalog means it is most likely writing usage instructions rather than trigger conditions. A rough estimate of about four characters per token is enough; switch to a real tokenizer when precision matters.

Activation: file-reading style versus a dedicated tool

Once the model decides to use a skill, how does the body enter the context? Two routes.

File-reading style: the catalog gave a location, and the model reads it with the file-reading tool it already has. The upside is no new mechanism at all, so any agent with file-reading capability supports skills immediately; that is why this format spread across dozens of clients. The cost is that the model may read the wrong path or read only half, and you have no explicit hook for deduplication or protection.

Dedicated tool style: give the model a tool named something like "open a skill," taking a name as its argument. The upside is that activation becomes an observable, interceptable call — you can deduplicate there, run a permission check, and put the skill directory and a resource listing into the return value. The cost is one more tool definition, and it requires the host to be willing to open a dedicated path for skills.

Neither is absolutely right, and the deciding factor is whether you control the host. Writing your own agent, use the tool style and take full control; building a general implementation to drop into somebody else's client, file-reading style's compatibility is irreplaceable.

Whichever route, the injected content should be wrapped in a structured tag and should add two things inside it: the absolute path of the skill directory (telling the model where relative paths resolve) and a listing of file names under scripts/, references/, and assets/.

Living a little longer: deduplication and compaction protection

With the steps above working, a demo holds up. But two problems surface once a session runs long.

Repeated activation. The model may select the same skill a second time in one session, having forgotten it already read it. The same instructions appearing twice in the context wastes tokens and easily interferes with itself when the two copies word things slightly differently. The fix is simple: keep an activated set and return immediately on a hit rather than injecting again.

Getting compacted away. When a long session triggers compaction, early messages get replaced by a summary. If a skill body falls in the compacted range, no error is raised at all — the model simply reverts quietly to how it behaves without the skill. What the user sees is "it was fine earlier and later it stopped following the convention," which is the hardest class of problem in this mechanism to diagnose.

So the message produced by activation should carry a protected marker, and compaction should keep the whole section or at least re-inject it once. The marker itself is simple; the hard part is remembering to add it. That whole craft of long-running sessions — compaction, memory files, subagent isolation — is covered far more systematically in the sister course, day 4 of Context Engineering in 5 Days. Today all you need is: a skill body is a high-priority retention item during compaction.

Source Reading

Today's lab is a runtime you can read line by line, six files with one job each, under four hundred lines in total. Read them in this order.

parse.ts is the foundation and the one whose details most repay attention: separating the frontmatter, the read-by-line fallback, and that set of warn-but-do-not-reject checks. Look closely at the single place that returns null, which is the missing description case.

scan.ts is traversal plus collisions. Two things are easy to miss inside findSkillDirs: returning as soon as SKILL.md is found (no drilling further), and the skip set and depth limit. scanSkills advances in scope order, first in wins, and a shadowed skill is recorded in shadowed with a warn-level diagnostic added.

catalog.ts has only two functions, buildCatalog splicing the catalog and catalogCost computing each entry's cost. It is so short it hardly looks important, but it is the only cost of the three stages repeated every turn, and it is worth staring at its output for a while.

activate.ts is the activation entry point: deduplication, tag wrapping, resource listing, and stamping the compaction-protected marker. listResources walks only the three conventional directories and takes only file names.

select.ts is the runtime's only network egress. One discipline of design matters here: which skill to select is a judgment made by the model, not by the runtime. A runtime doing its own keyword matching degrades the description's semantic judgment into string hits, and day three's whole trigger-testing apparatus loses its meaning. The naive match in offline mode exists only to make the flow runnable, and whether a description is written well must be verified with a real model, with the offline switch off.

index.ts strings the three stages together for one run and prints eight self-checks at the end. Run the solution first to see all eight green, then run the starter to see how they go red — which self-checks each of the five exercise points maps to becomes obvious.

Hands-On Lab

The six skills in fixtures/ are deliberately broken: one missing a description, one whose name disagrees with its directory, one with a bare colon in its description, one with only a README, and a same-named pair to demonstrate shadowing. Look through them yourself before running, guess which will load and which will only leave warnings, then run and check your answers.

1. Get the solution running and see how many skills were scanned, what the catalog looks like, and which message the body landed in after activation.
2. Complete the scanning function in the starter, handling a project-level and user-level name collision and printing one shadowed warning.
3. Complete the frontmatter parsing so a missing description is skipped and a name disagreeing with the directory only warns.
4. Complete the catalog injection and cost estimate so a structured list of available skills appears in the system prompt.
5. Complete the deduplication in the activation entry point and verify only activated bodies entered the context.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward the implementation points of the runtime's three stages, lenient parsing and collision handling, and activation styles and context protection. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets. The high-frequency labels for the domestic and overseas markets are there so you can pick by target market.

Checklist and Tomorrow

• Implement a skill scanner that handles scope priority and name collisions
• Leniently parse SKILL.md frontmatter, degrading gracefully rather than crashing on malformed input
• Inject the directory into the system prompt, and implement an activation entry point that reads the body on demand
• Explain the asymmetry that disclosure is paid every turn while activation is paid once, and which spec constraints it explains
• All 5 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D6) we go from one person's folder to a team's capability pack: how a set of skills is packaged as a plugin, how a marketplace publishes it, how versions are bumped, and the table this course has owed you for five days — what function calling, MCP, and Skills each actually govern, and when to reach for which. Having now seen from the runtime's side how a skill gets loaded, that table will read much more easily tomorrow.