Loading Skills: Scanning, Progressive Disclosure, and Trigger Judgment — Bringing Experience to the Table on Demand

Skills versus tools: one supplies capability, the other supplies process

A tool is capability; a skill is process. A tool lets the Agent do what it otherwise could not — without run_command it cannot run the tests, and no amount of knowing would help. A skill makes it do correctly what it already can do: of course it can run tests, but not which command this repo uses, which output line to read first, or what counts as "did not actually run."

That division shows up cleanly in the code: not one line written today touches the tool registry. Yesterday MCP pushed five remote tools into it; today we push zero. A skill occupies no slot in the tool list, and the model never "calls" one — it merely finds, at the right moment, that a piece of text has appeared in front of it.

The upside: skills have no practical ceiling, tools do. The tool table goes out with every request, and each extra tool parks another schema in the prompt prefix; past a few dozen, the odds of picking the wrong tool rise visibly. A skill's resident cost is one line of description, and the body is never resident at all.

The price: a skill cannot be guaranteed to run. A tool call has definite semantics — the model emits a call, we execute it, bad arguments get handed back. A skill is only text; the model can read it and not follow it, and you have no mechanism that stops that. A rule that must hold should never live only in a skill: in mca, "snapshot before writing a file" is in the code (D14), not on a craft card. Craft cards govern judgment; code governs discipline.

Against yesterday: MCP solves "the tools live somewhere else," skills solve "the experience lives somewhere else." The first needs wiring, a protocol and a trust boundary; the second needs text and loading rules. The three-way comparison is in the Skills course, day six; this course does not repeat it.

Directory conventions and metadata validation

The shape of a skill pack is simple: a directory, a SKILL.md inside it, and optionally a few attachments.

skills/
  calc-conventions/
    SKILL.md
  release-notes/
    SKILL.md
    scripts/bump-version.mjs

SKILL.md opens with YAML frontmatter. The specification requires exactly two fields: name and description. This lab adds four extensions of this implementation (domain, priority, triggers, paths). They are not in the specification — only our loader knows them — and unless that is said out loud you will assume they are standard and be baffled by the next client.

---
name: calc-conventions
description: "Numeric conventions for the calc module. Follow it when editing src/calc.js or discussing divide-by-zero behavior."
domain: calc
priority: 20
triggers: [divide, division by zero, divisor is 0, zero divisor]
paths:
  - src/calc.js
  - test/calc.test.js
---

The first decision in parsing that header is not to pull in a YAML library. Beyond the zero-dependency rule, full YAML is far more expressive than skill metadata needs, and the surplus is all risk — anchors, merge keys, and the famous implicit conversions (the string no becoming boolean false), each producing "the same SKILL.md behaves differently in two clients." So we implement a stated subset of four shapes: bare scalar, quoted scalar, inline array, indented multi-line array. One hard line: a line we do not understand is an error, never a guess. Guessing means the author got it wrong and nobody told him, so the skill quietly never fires — the hardest failure in a skill system to track down.

The second decision hides in a line that looks like one line: how you split the header from the body. The intuitive version splits on --- and takes the middle piece, and it is wrong — a horizontal rule is legal Markdown, and any document of length has one. Splitting on the delimiter shreds the body, presenting as "half the skill text mysteriously vanished," while small files look fine. Scan by line instead: the first line must be ---, then find the first --- after it standing alone on its own line.

export function splitFrontmatter(text: string): { head: string; body: string } {
  const lines = text.replace(/^/, '').split('\n')
  if ((lines[0] ?? '').trim() !== FENCE) {
    throw new FrontmatterError('the first line of the file must be ---')
  }
  // From line two, find the first --- standing alone. Splitting on the
  // delimiter would treat a horizontal rule in the body as a boundary too.
  const end = lines.findIndex((line, index) => index > 0 && line.trim() === FENCE)
  if (end === -1) throw new FrontmatterError('the frontmatter has no closing --- line')
  return {
    head: lines.slice(1, end).join('\n'),
    body: lines.slice(end + 1).join('\n').replace(/^\n+/, ''),
  }
}

FENCE = "---"
 
 
def split_frontmatter(text: str) -> tuple[str, str]:
    lines = text.lstrip("").split("\n")
    if not lines or lines[0].strip() != FENCE:
        raise FrontmatterError("the first line of the file must be ---")
    # next + generator: stop at the first hit, fall back to a default,
    # and never build the whole table first
    end = next((i for i, line in enumerate(lines[1:], 1) if line.strip() == FENCE), None)
    if end is None:
        raise FrontmatterError("the frontmatter has no closing --- line")
    return "\n".join(lines[1:end]), "\n".join(lines[end + 1 :]).lstrip("\n")

The validation layer's rule is skip it and say why — neither silent skipping nor throwing all the way out. The first leaves the author believing his pack works; the second lets one broken pack stop mca starting at all. This is yesterday's discipline about an offline server restated: when one part breaks, the worst outcome should be one missing part. The lab ships a pack with no description; at startup it is skipped, and the log names the directory, the missing field, and why it cannot be omitted.

Three-stage loading

Back to the contradiction. Progressive disclosure answers it by splitting "knowing it exists" from "knowing what it says," then adding a third thing.

flowchart TD
  A[Scan the skills directory at startup] --> B[Stage one resident summary<br/>one line per skill name plus purpose]
  B --> C{What did this sentence match}
  C -->|nothing matched| D[Stage two injects 0 characters]
  C -->|some matched| E[Stage two full text on demand<br/>loaded by score through two gates]
  E --> F[Stage three attachments on demand<br/>a command line only never the script]
  F --> G[The model decides whether to run it<br/>running it is a tool call]

The three stages have different criteria, and that is the point worth memorizing, because the criterion decides the shape of the cost:

Stage one is one line per skill, its description. That line is the entire basis on which the model judges whether to use the skill, so it should say "when to use me," not "what I am" — how to write one is covered in the Skills course, day two; here we only consume it. The summaries append to the system prompt: their criterion is independent of what the user said, which makes them inherently resident.

Stage two injects the matching bodies as one message. Two details: the role is user, not system — this is material for this turn, not a standing rule, and as system it would be weighted like a permanent instruction in every later turn (the same call as day eight's reference injection); and it goes ahead of the reference injection, because the relationship is "rules first, then material" — by the time the model reads src/calc.js, the convention that division by zero must throw should already be in front of it.

Stage three is attachments. The release-notes skill ships a version-bumping script, and when we inject its body we give one command line plus one sentence of explanation, and read not a character of the script. That is the definition: a script is there to be run, not read aloud to the model. Three hundred lines poured into the context invites the model to understand it and write its own version, far worse than running it. And give a directly runnable command line, not a path — given a path the model reads the file first, and stage three collapses back into stage two.

One misreading deserves clearing up: progressive disclosure saves context, not disk IO. The scan does read every SKILL.md in full, since reaching the frontmatter means reading the file head anyway. Reading a local file is microseconds; putting that text into every request is what you pay for by the token and what eats the window. Keeping the two apart stops you writing pointless optimizations like lazy file handles in the name of saving tokens.

Trigger judgment: the two kinds of mistake do not cost the same

Judgment uses three conditions, ordered by trust: an explicit mention by the user (a hundred points), a path match (ten each), a keyword match (three each). The score only ranks and breaks ties, and the priority field never takes part in deciding whether something matched at all — let it in and a high-priority skill shows up in a sentence with nothing to do with it.

What deserves real thought is the mistakes. Over-triggering and missing a trigger do not cost the same. Over-triggering spends a little context and is visible — the injection ledger shows an extra line and you know at once. A missing trigger means the model answers from general knowledge, answers plausibly, and nothing hints that a convention went unread; you find out at code review, when division by zero once again returns infinity.

So the default posture is "better one card too many," with the brake in the budget layer rather than the judgment layer. This runs against instinct: most people write the triggers tightly, the skills never fire, and the conclusion becomes "this whole mechanism is useless."

One trap catches almost everybody: triggers in a whitespace-separated language must match on word boundaries. Without them, a trigger written test is matched by latest and contest — the single largest source of false positives. Scripts written without spaces between words can only match as substrings, having no word boundary to appeal to. This must not be left to the skill author, who is thinking about what his skill is for, not about whether that string hides inside other words.

export function hasWord(text: string, word: string): boolean {
  const target = word.trim()
  if (target === '') return false
  const haystack = text.toLowerCase()
  const needle = target.toLowerCase()
  // Anything non-ASCII matches as a substring: scripts written without
  // spaces between words give us no word boundary to appeal to.
  if (/[^\x20-\x7e]/.test(target)) return haystack.includes(needle)
  // A boundary here only means "neither side is alphanumeric", so a
  // multi-word trigger such as node --test still matches.
  const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
  return new RegExp(`(^|[^a-z0-9])${escaped}($|[^a-z0-9])`).test(haystack)
}

import re
 
 
def has_word(text: str, word: str) -> bool:
    target = word.strip()
    if not target:
        return False
    haystack, needle = text.lower(), target.lower()
    if not target.isascii():  # no spaces between words, so no boundary exists
        return needle in haystack
    # escape first, or a - or . inside a trigger becomes a metacharacter
    pattern = rf"(^|[^a-z0-9]){re.escape(needle)}($|[^a-z0-9])"
    return re.search(pattern, haystack) is not None

After judging, print why each skill matched. Not decoration: when a trigger is missed, those lines are the user's only evidence for whether the trigger words were too narrow, the paths wrong, or the skill never installed at all.

Skills conflict: what to do when two match at once

The lab ships two contradictory calc conventions: the current one says divide by zero must throw, the archived one says it returns infinity. Their triggers overlap, so "fix the divide-by-zero problem" matches both.

Load both and the result is not that the model knows more; it picks one at random and you cannot tell which. A skill conflict is contradiction, not duplication, so both gates are mandatory:

Gate one, domain exclusion. Make the author declare a domain, and load only the highest-scoring skill per domain. Far more reliable than hoping the model reconciles two contradictory rule sets — it cannot, it will just choose one.

Gate two, a total character budget. What does not fit does not load, and the reason must be stated: silent dropping makes people believe the skill is written wrong when the budget was too small, and those two problems have opposite fixes.

for (const hit of hits) {
  // Gate one: one skill per domain, the highest score. Two contradictory
  // conventions on the table only make the model pick one at random.
  const winner = domains.get(hit.skill.domain)
  if (winner) {
    decisions.push({ hit, loaded: false, why: `same ${hit.skill.domain} domain as ${winner}, which won` })
    continue
  }
  const block = await renderSkill(hit.skill)
  // Gate two: the budget. Say why something was left out, or it gets
  // mistaken for a broken skill.
  if (used + block.length > budget) {
    decisions.push({ hit, loaded: false, why: `body is ${block.length} chars, only ${budget - used} left` })
    continue
  }
  domains.set(hit.skill.domain, hit.skill.id)
  used += block.length
  blocks.push(block)
  decisions.push({ hit, loaded: true, why: `expanded, ${block.length} chars` })
}

for hit in hits:  # hits is already sorted by score, descending
    winner = domains.get(hit.skill.domain)
    if winner:  # gate one: one skill per domain, the highest score
        decisions.append(Decision(hit, False, f"same {hit.skill.domain} domain as {winner}, which won"))
        continue
    block = await render_skill(hit.skill)
    if used + len(block) > budget:  # gate two: budget, and state the reason
        decisions.append(Decision(hit, False, f"body is {len(block)} chars, only {budget - used} left"))
        continue
    domains[hit.skill.domain] = hit.skill.id
    used += len(block)
    blocks.append(block)
    decisions.append(Decision(hit, True, f"expanded, {len(block)} chars"))

How much it saves: three loading strategies side by side

A mechanism that saves nothing is not worth keeping, and you only see that by putting the numbers side by side. The figures below come from this lab's self-test, all four skill packs in the repository, reproducible offline. One caveat: these tokens are estimates, from the default coefficients of day twelve — today runs entirely offline, so there is no real usage to calibrate against. Two runs on one machine give identical results, but the number equals no model's actual tokenization. Exact counting and calibration were covered that day; here we only borrow its estimator.

Two conclusions hide in that table.

First, the bulk of the benefit lands on the turns that match nothing. In a real session most turns have nothing to do with any craft card — the user asks what a function does, or has a log read. Those save 87%, while the matching turn saves 25%. Progressive disclosure does not make every turn cheaper; it makes the irrelevant turns free.

Second, this ledger improves as the skill count grows. Full loading grows linearly with it. Stage one also grows linearly, with a coefficient an order of magnitude smaller — one line of description against a page of body. Stage two depends only on how many skills this sentence matched, not on the total. Four packs save 25%; with thirty, the matching turn still loads two or three. That is where this design earns its keep.

Back to the division we started with: when the lab finishes, the tool list is eight entries from start to end, not one more, and the code the model produced matches the team's convention to the character. That is the difference between experience and capability.

Source Reading

Hands-On Lab

The lab ships five skill packs: two contradictory calc conventions, a testing handbook, a release procedure with an attached script, and one deliberately broken pack missing its description. All five exercises are "the intuitive version works perfectly on small data" traps: splitting frontmatter on the delimiter, loading a pack with a missing field, reading the script body into the context, judging on keywords with no word boundaries, and loading every skill that matched. The starter passes seven of fourteen unmodified.

1. Rewrite the frontmatter split to scan by line and watch the first check turn green — it was failing on a Markdown horizontal rule in the body.
2. Add the four metadata validations and watch the broken pack get skipped, with the missing field named in the log.
3. Change attachments from "read the body" to "one command line plus one sentence" and watch the script's function names disappear from the injected text.
4. Add path conditions and word boundaries to the judgment, then see the path reason appear among the hits and test stop matching latest.
5. Add the domain and budget gates, run MOCK=1 SELFTEST=1 pnpm start to see 14/14 passed, then use the README's pipe commands to compare what the three loading strategies each cost.

Acceptance is five ticks: the self-test prints 14/14 passed; the broken pack is skipped with the missing field named; only the higher-scoring of the two contradictory calc conventions reaches the table; the attachment contributes a command line while its body never enters the context; and a sentence matching nothing injects zero characters at stage two.

Interview Questions

Today's three questions test implementation judgment about progressive disclosure and where a skill's boundary lies, not "what are Skills":

1. How many stages does progressive disclosure have? What is each stage's criterion?
2. Where is the boundary between a skill and a tool? How do you choose for the same job?
3. How do you design a skill's trigger conditions? Which is harder to diagnose, over-triggering or missing a trigger?

Full prompts, analyses and key points are in this course's day-sixteen question bank. Question three discriminates most — most answer "write accurate trigger words," and few can say that the two kinds of mistake cost differently, so the default posture should be one card too many, and explain why.

Checklist and Tomorrow

• I can state the division between skills and tools, and why no line of today's code touches the tool registry
• I can state the price that a skill cannot be guaranteed to run, and which rules must not live only in a skill
• I can explain why we skip a full YAML library, and what our subset's hard line is
• I can say why splitting frontmatter on the delimiter always breaks, and why only long documents expose it
• I can state each stage's criterion, and how it decides the shape of the cost
• I can explain that progressive disclosure saves context, not disk IO
• I can say why the stage-two injection uses the user role rather than system
• I can explain why stage three gives a command line instead of only a path
• I can say why over-triggering and missing a trigger cost differently, and where the brake belongs
• I can state that ASCII triggers need word boundaries while unspaced scripts only match substrings, and why that is not the author's choice
• I can explain that a skill conflict is contradiction rather than duplication, and what each gate blocks

Tomorrow is D17, "Subagents and Parallelism: Independent Context, a Tool Allowlist, Worktree Isolation, and Result Aggregation." The contrast is worth thinking about in advance: today puts a piece of text in front of the model at the right moment; tomorrow sends a whole model out to work. Both are "on demand," and the cost differs by two orders of magnitude.