@namzu/sdk 15.0.0 → 16.0.0

package/dist/utils/frontmatter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The one frontmatter reader.
+ *
+ * A `SKILL.md`, a command file, and anything else this kernel reads from a
+ * markdown file with a `---` fence all come through here. There were three
+ * readers before this one and two of them disagreed on the same input: this
+ * one **threw** on malformed frontmatter, and a second **silently returned no
+ * metadata**, so the same file was a hard error in one code path and a skill
+ * named after its own directory with "(no description)" in the other. Refuse
+ * versus degrade, on one file shape, is the divergence this module exists to
+ * end — see `docs/conventions/refuse-do-not-degrade.md`.
+ *
+ * **Deliberately not a YAML parser.** It is a flat key/value splitter with one
+ * level of nesting, and it refuses the constructs in {@link UNSUPPORTED_YAML}
+ * rather than mangling them. That refusal is the design: a reader that
+ * half-understands YAML produces a value that passes validation and means
+ * nothing.
+ *
+ * That refusal is now total for lists. A *block* sequence
+ *
+ * ```yaml
+ * allowed-tools:
+ *   - Read
+ * ```
+ *
+ * used to be silently dropped — its lines carry no `:` and were skipped, so the
+ * key came back **absent** — while the flow form `[Read, Grep]` threw. One
+ * spelling of a list was a hard error and the other was silence, and the silent
+ * one is the shape an author actually writes, because the block form is the
+ * natural YAML for a list.
+ *
+ * It matters most for a key like `allowed-tools`: a skill that asked for `Bash`
+ * and silently did not get it is indistinguishable from one that never asked,
+ * which is a capability quietly not granted rather than a formatting nicety.
+ * Both readers this replaced behaved that way, so it was inherited rather than
+ * introduced; it is now refused, naming the key.
+ *
+ * **Vocabulary belongs to the caller.** This returns the parsed map; it does
+ * not know what a skill needs or what a command needs, and it validates no
+ * field names. Widening one caller's metadata type to cover another's is how a
+ * skill-shaped API comes to mean something it does not.
+ */
+/**
+ * What one frontmatter key holds: a scalar, or a block of indented pairs.
+ *
+ * A discriminated union rather than two parallel maps, because the source
+ * format cannot express both at once. The first shape of this type had
+ * `data: Record<string, string>` beside `blocks: Record<string, Record<…>>`,
+ * which let one key sit in both — a state no YAML file can produce. Every
+ * caller would then have had to decide a precedence for a case that cannot
+ * arrive, and the ones who did not would be carrying a latent bug against a
+ * shape that told them the case existed. Removing the state beats documenting
+ * it.
+ */
+export type FrontmatterValue = {
+    readonly kind: 'scalar';
+    readonly value: string;
+} | {
+    readonly kind: 'mapping';
+    readonly entries: Readonly<Record<string, string>>;
+};
+export interface ParsedFrontmatter {
+    /**
+     * Every top-level key, in the order the file declared it.
+     *
+     * A key whose value is empty and which has no indented lines under it is
+     * absent: it declared nothing. Narrow on `kind` to read it —
+     *
+     * ```ts
+     * const d = values.description
+     * if (d?.kind !== 'scalar') throw new Error('description must be a scalar')
+     * use(d.value)
+     * ```
+     */
+    readonly values: Readonly<Record<string, FrontmatterValue>>;
+    /** Everything after the closing fence, trimmed. */
+    readonly body: string;
+}
+/**
+ * Parse a markdown file's `---` frontmatter.
+ *
+ * @param raw The file's full contents. LF and CRLF both parse.
+ * @param source A label for error messages — a path, or a phrase naming the
+ *   file. Used verbatim, so the caller controls how its own errors read.
+ * @throws If the frontmatter is absent, unclosed, or uses YAML this reader
+ *   does not implement. It never returns a partial or empty result to stand in
+ *   for a file it could not read.
+ */
+export declare function parseFrontmatter(raw: string, source: string): ParsedFrontmatter;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/utils/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/utils/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AA8DH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,CAAA;AAEnF,MAAM,WAAW,iBAAiB;IACjC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAA;IAE3D,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAoG/E"}

package/dist/utils/frontmatter.js

@@ -0,0 +1,212 @@
+/**
+ * The one frontmatter reader.
+ *
+ * A `SKILL.md`, a command file, and anything else this kernel reads from a
+ * markdown file with a `---` fence all come through here. There were three
+ * readers before this one and two of them disagreed on the same input: this
+ * one **threw** on malformed frontmatter, and a second **silently returned no
+ * metadata**, so the same file was a hard error in one code path and a skill
+ * named after its own directory with "(no description)" in the other. Refuse
+ * versus degrade, on one file shape, is the divergence this module exists to
+ * end — see `docs/conventions/refuse-do-not-degrade.md`.
+ *
+ * **Deliberately not a YAML parser.** It is a flat key/value splitter with one
+ * level of nesting, and it refuses the constructs in {@link UNSUPPORTED_YAML}
+ * rather than mangling them. That refusal is the design: a reader that
+ * half-understands YAML produces a value that passes validation and means
+ * nothing.
+ *
+ * That refusal is now total for lists. A *block* sequence
+ *
+ * ```yaml
+ * allowed-tools:
+ *   - Read
+ * ```
+ *
+ * used to be silently dropped — its lines carry no `:` and were skipped, so the
+ * key came back **absent** — while the flow form `[Read, Grep]` threw. One
+ * spelling of a list was a hard error and the other was silence, and the silent
+ * one is the shape an author actually writes, because the block form is the
+ * natural YAML for a list.
+ *
+ * It matters most for a key like `allowed-tools`: a skill that asked for `Bash`
+ * and silently did not get it is indistinguishable from one that never asked,
+ * which is a capability quietly not granted rather than a formatting nicety.
+ * Both readers this replaced behaved that way, so it was inherited rather than
+ * introduced; it is now refused, naming the key.
+ *
+ * **Vocabulary belongs to the caller.** This returns the parsed map; it does
+ * not know what a skill needs or what a command needs, and it validates no
+ * field names. Widening one caller's metadata type to cover another's is how a
+ * skill-shaped API comes to mean something it does not.
+ */
+/**
+ * A closing fence is a line of its own, not `---` wherever it appears.
+ *
+ * An unanchored search found `---` inside a quoted value, inside a URL, inside
+ * prose — and cut the frontmatter there, which both truncated the metadata AND
+ * spilled the rest of it into the body, where it reaches the system prompt
+ * verbatim.
+ *
+ * `\r?` is explicit rather than incidental. `$` under `/m` already matches
+ * before a `\r` because JavaScript counts `\r` as a line terminator, so this
+ * pattern worked on CRLF by accident before it worked on purpose. Naming the
+ * carriage return keeps the next edit from removing a property nobody knew was
+ * being relied on — a file authored on Windows is the ordinary case, not the
+ * exotic one.
+ */
+const FRONTMATTER_FENCE = /^---[ \t]*\r?$/m;
+const FRONTMATTER_DELIMITER = '---';
+/**
+ * Splits on any of the three line endings — CRLF, LF, and a lone CR.
+ *
+ * The `\r?\n` half is defence in depth and was measured as such: reducing it to
+ * `/\n/` fails no test, because {@link normalizeScalar} trims the stray `\r`
+ * off every value anyway. The fence is the load-bearing half for CRLF, and that
+ * one has a mutation profile.
+ *
+ * The lone `\r` is not decoration. Without it a CR-only file is one single
+ * "line", and the whole frontmatter collapses into the first key: `name` came
+ * back as `"a-skill\rdescription: d"` — a *wrong value*, silently, which is the
+ * failure this module exists to end.
+ *
+ * `loadSkill` was accidentally protected, though not in the way first written
+ * here: the collapse leaves no `description` key at all, so the required-field
+ * check refused the file before any value could be used. A caller that
+ * validates nothing — which is every caller this is now exported for — would
+ * have taken the mangled name.
+ */
+const LINE_SPLIT = /\r\n|\r|\n/;
+/**
+ * YAML this reader does not implement, refused rather than mangled.
+ *
+ * The documented contract says "YAML frontmatter" with no restriction — so an
+ * author has every reason to write a block scalar or a flow sequence, and no
+ * reason to expect what happened next. A `description: >-` followed by an
+ * indented paragraph produced the literal string `">-"`, which passed
+ * validation and registered with no warning; the skill then existed and was
+ * never selected, because its description said nothing. A `[Read, Grep]`
+ * became that literal text and was interpolated straight into the prompt.
+ *
+ * Refusing names the line and the file. That is worse for exactly one file —
+ * the one already silently broken — and better for everyone looking for it.
+ */
+const UNSUPPORTED_YAML = [
+    { pattern: /^[>|][-+]?\s*$/, what: 'a block scalar (`>` or `|`)' },
+    { pattern: /^\[.*\]$/, what: 'a flow sequence (`[a, b]`)' },
+    { pattern: /^\{.*\}$/, what: 'a flow mapping (`{a: b}`)' },
+];
+/**
+ * Parse a markdown file's `---` frontmatter.
+ *
+ * @param raw The file's full contents. LF and CRLF both parse.
+ * @param source A label for error messages — a path, or a phrase naming the
+ *   file. Used verbatim, so the caller controls how its own errors read.
+ * @throws If the frontmatter is absent, unclosed, or uses YAML this reader
+ *   does not implement. It never returns a partial or empty result to stand in
+ *   for a file it could not read.
+ */
+export function parseFrontmatter(raw, source) {
+    const trimmed = raw.trimStart();
+    if (!trimmed.startsWith(FRONTMATTER_DELIMITER)) {
+        throw new Error(`${source} has no YAML frontmatter`);
+    }
+    const closing = FRONTMATTER_FENCE.exec(trimmed.slice(FRONTMATTER_DELIMITER.length));
+    if (!closing) {
+        throw new Error(`${source} has unclosed frontmatter`);
+    }
+    const endIdx = FRONTMATTER_DELIMITER.length + closing.index;
+    const frontmatterRaw = trimmed.slice(FRONTMATTER_DELIMITER.length, endIdx).trim();
+    const body = trimmed.slice(endIdx + closing[0].length).trim();
+    // `Map`, not an object literal, because the keys come from an untrusted
+    // file. `blocks[key] = …` on a plain object with `key === '__proto__'`
+    // reaches `Object.prototype` through the inheritance chain and writes
+    // **there** — a frontmatter file could set `Object.prototype.metadata` and
+    // poison every object in the process. That is not theoretical: it was
+    // caught here by an adversarial pass, and the poisoned prototype then
+    // showed up in the metadata of an unrelated skill loaded afterwards.
+    // A `Map` has no prototype chain for string keys, and `Object.fromEntries`
+    // *defines* own properties rather than assigning through setters, so the
+    // round trip is safe at both ends.
+    const data = new Map();
+    const blocks = new Map();
+    let currentKey;
+    for (const line of frontmatterRaw.split(LINE_SPLIT)) {
+        if (!line.trim() || line.trimStart().startsWith('#'))
+            continue;
+        if (/^\s/.test(line)) {
+            if (!currentKey)
+                continue;
+            // A block sequence item. Refused, not skipped.
+            //
+            // These lines carry no `:`, so the `continue` below used to drop them
+            // and the key — having no scalar value and no mapping entries — came
+            // back ABSENT. The flow form `[Read, Grep]` already threw, so one
+            // spelling of a list was a hard error and the other was silence.
+            //
+            // The block form is the more natural YAML for a list, which is what
+            // made this worth closing: `allowed-tools` is a list, so this is the
+            // shape an author actually writes, and a skill that asked for `Bash`
+            // and silently did not get it is indistinguishable from one that never
+            // asked. A capability quietly not granted is the worst thing this
+            // reader can produce.
+            if (/^\s*-\s/.test(line)) {
+                throw new Error(`${source}: "${currentKey}" uses a block sequence (a "- " list), which this reader does not support. Write it as a single-line value instead. Refusing rather than reading "${currentKey}" as absent, which is what silently dropping the list would mean.`);
+            }
+            const colonIdx = line.indexOf(':');
+            if (colonIdx === -1)
+                continue;
+            const key = line.slice(0, colonIdx).trim();
+            const value = normalizeScalar(line.slice(colonIdx + 1));
+            if (!key || !value)
+                continue;
+            let block = blocks.get(currentKey);
+            if (!block) {
+                block = new Map();
+                blocks.set(currentKey, block);
+            }
+            block.set(key, value);
+            continue;
+        }
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const value = normalizeScalar(line.slice(colonIdx + 1));
+        assertReadableScalar(key, value, source);
+        currentKey = key;
+        if (value)
+            data.set(key, value);
+    }
+    // A key cannot be a scalar and a mapping at once — no YAML file can say
+    // that — so refusing here is what makes the illegal state unrepresentable
+    // in the returned type rather than merely undocumented. The alternative,
+    // picking a precedence, would silently drop half of what the author wrote.
+    for (const key of blocks.keys()) {
+        if (!data.has(key))
+            continue;
+        throw new Error(`${source}: "${key}" has both a value and an indented block. A key is one or the other — remove the value, or un-indent the lines beneath it.`);
+    }
+    const values = new Map();
+    for (const [key, value] of data) {
+        values.set(key, { kind: 'scalar', value });
+    }
+    for (const [key, entries] of blocks) {
+        values.set(key, { kind: 'mapping', entries: Object.fromEntries(entries) });
+    }
+    return { values: Object.fromEntries(values), body };
+}
+function normalizeScalar(value) {
+    return value
+        .trim()
+        .replace(/^["']|["']$/g, '')
+        .trim();
+}
+function assertReadableScalar(key, value, source) {
+    for (const { pattern, what } of UNSUPPORTED_YAML) {
+        if (!pattern.test(value))
+            continue;
+        throw new Error(`${source}: "${key}" uses ${what}, which this reader does not support. Write it as a single-line value instead. Refusing rather than accepting a "${key}" that would read as ${JSON.stringify(value)}.`);
+    }
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/utils/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/utils/frontmatter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "15.0.0",
+  "version": "16.0.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",

package/src/public-runtime.ts

@@ -142,6 +142,11 @@ export {
 	resolveSkillChain,
 	SkillRegistry,
 } from './skills/index.js'
+// The one frontmatter reader. `loadSkill` is built on it, and a host reading
+// its own markdown — a command file, a prompt template — uses the same one
+// rather than hand-rolling a second that disagrees about CRLF or about whether
+// a malformed file throws or quietly returns nothing.
+export { parseFrontmatter } from './utils/frontmatter.js'
 
 // ─── the agent directory ─────────────────────────────────────────────────
 //

package/src/public-types.ts

@@ -99,6 +99,7 @@ export type {
 export type { AdvisoryCallContext, AdvisoryExecutionResult } from './advisory/index.js'
 
 export type { ModelPricing } from './utils/cost.js'
+export type { FrontmatterValue, ParsedFrontmatter } from './utils/frontmatter.js'
 export type { Logger } from './utils/logger.js'
 export type { ShellCompressOptions, ShellCompressResult } from './utils/shell-compress.js'
 

package/src/skills/loader.ts

@@ -6,151 +6,98 @@ import type {
 	SkillLoadResult,
 	SkillMetadata,
 } from '../types/skills/index.js'
+import { type ParsedFrontmatter, parseFrontmatter } from '../utils/frontmatter.js'
 import { getRootLogger } from '../utils/logger.js'
 
 const logger = getRootLogger().child({ component: 'SkillLoader' })
 
 const SKILL_FILENAME = 'SKILL.md'
-const FRONTMATTER_DELIMITER = '---'
 
-interface ParsedSkillMd {
-	metadata: SkillMetadata
-	body: string
+/**
+ * How this file's errors name themselves. Passed to the shared reader so a
+ * frontmatter failure still reads as a `SKILL.md` failure — the reader is
+ * generic, the message is not.
+ */
+function sourceLabel(dirPath: string): string {
+	return `SKILL.md at "${dirPath}"`
 }
 
-function parseSkillMd(raw: string, dirPath: string): ParsedSkillMd {
-	const trimmed = raw.trimStart()
-
-	if (!trimmed.startsWith(FRONTMATTER_DELIMITER)) {
-		throw new Error(`SKILL.md at "${dirPath}" has no YAML frontmatter`)
-	}
-
-	// Anchored to a line of its own. An unanchored search found `---`
-	// anywhere — inside a quoted value, inside a URL, inside prose — and cut
-	// the frontmatter there, which both truncated the metadata AND spilled
-	// the rest of the frontmatter into `body`, where it reaches the system
-	// prompt verbatim.
-	const closing = FRONTMATTER_FENCE.exec(trimmed.slice(FRONTMATTER_DELIMITER.length))
-	if (!closing) {
-		throw new Error(`SKILL.md at "${dirPath}" has unclosed frontmatter`)
-	}
-
-	const endIdx = FRONTMATTER_DELIMITER.length + closing.index
-	const frontmatterRaw = trimmed.slice(FRONTMATTER_DELIMITER.length, endIdx).trim()
-	const body = trimmed.slice(endIdx + closing[0].length).trim()
-
-	const metadata = parseFlatYaml(frontmatterRaw, dirPath)
-
-	return { metadata, body }
+/**
+ * The skill vocabulary, applied to a generic parse.
+ *
+ * Splitting the file is {@link parseFrontmatter}'s job and knowing what a
+ * skill requires is this function's. A command file goes through the same
+ * reader and validates an entirely different set of keys.
+ */
+/**
+ * Read one key, narrowed to the shape this field is declared to have.
+ *
+ * `Object.hasOwn`, not a bare `values[key]`: a plain property read walks the
+ * prototype chain, so a `Object.prototype.description` poisoned by anything
+ * else in the process would be picked up here as though the file had declared
+ * it. The parser can no longer create that poison; this is the other end of
+ * the same guarantee.
+ */
+function scalarAt(values: ParsedFrontmatter['values'], key: string): string | undefined {
+	if (!Object.hasOwn(values, key)) return undefined
+	const found = values[key]
+	return found?.kind === 'scalar' ? found.value : undefined
 }
 
-function parseFlatYaml(raw: string, dirPath: string): SkillMetadata {
-	const lines = raw.split('\n')
-	const kv: Record<string, string> = {}
-	const metadata: Record<string, string> = {}
-	let section: 'metadata' | undefined
-
-	for (const line of lines) {
-		if (!line.trim() || line.trimStart().startsWith('#')) continue
-
-		if (/^\s/.test(line)) {
-			if (section !== 'metadata') continue
-			const colonIdx = line.indexOf(':')
-			if (colonIdx === -1) continue
-			const key = line.slice(0, colonIdx).trim()
-			const value = normalizeYamlScalar(line.slice(colonIdx + 1).trim())
-			if (key && value) metadata[key] = value
-			continue
-		}
-
-		const colonIdx = line.indexOf(':')
-		if (colonIdx === -1) continue
-		const key = line.slice(0, colonIdx).trim()
-		const value = normalizeYamlScalar(line.slice(colonIdx + 1).trim())
+function mappingAt(
+	values: ParsedFrontmatter['values'],
+	key: string,
+): Readonly<Record<string, string>> | undefined {
+	if (!Object.hasOwn(values, key)) return undefined
+	const found = values[key]
+	return found?.kind === 'mapping' ? found.entries : undefined
+}
 
-		assertReadableScalar(key, value, dirPath)
+function toSkillMetadata(parsed: ParsedFrontmatter, dirPath: string): SkillMetadata {
+	const source = sourceLabel(dirPath)
+	const { values } = parsed
 
-		section = key === 'metadata' ? 'metadata' : undefined
-		if (value) kv[key] = value
-	}
+	const name = scalarAt(values, 'name')
+	const description = scalarAt(values, 'description')
 
-	if (!kv.name) {
-		throw new Error(`SKILL.md at "${dirPath}" missing required field: name`)
+	if (!name) {
+		throw new Error(`${source} missing required field: name`)
 	}
-	if (!kv.description) {
-		throw new Error(`SKILL.md at "${dirPath}" missing required field: description`)
+	if (!description) {
+		throw new Error(`${source} missing required field: description`)
 	}
 
-	validateSkillName(kv.name, dirPath)
-	validateDescription(kv.description, dirPath)
+	validateSkillName(name, dirPath)
+	validateDescription(description, dirPath)
 
-	const skillMetadata: SkillMetadata = {
-		name: kv.name,
-		description: kv.description,
-	}
+	const skillMetadata: SkillMetadata = { name, description }
 
-	if (kv.license) {
-		skillMetadata.license = kv.license
+	const license = scalarAt(values, 'license')
+	if (license) {
+		skillMetadata.license = license
 	}
 
-	if (kv.compatibility) {
-		if (kv.compatibility.length > 500) {
-			throw new Error(`SKILL.md at "${dirPath}": compatibility exceeds 500 characters`)
+	const compatibility = scalarAt(values, 'compatibility')
+	if (compatibility) {
+		if (compatibility.length > 500) {
+			throw new Error(`${source}: compatibility exceeds 500 characters`)
 		}
-		skillMetadata.compatibility = kv.compatibility
+		skillMetadata.compatibility = compatibility
 	}
 
-	if (kv['allowed-tools']) {
-		skillMetadata.allowedTools = kv['allowed-tools']
+	const allowedTools = scalarAt(values, 'allowed-tools')
+	if (allowedTools) {
+		skillMetadata.allowedTools = allowedTools
 	}
 
-	if (Object.keys(metadata).length > 0) {
-		skillMetadata.metadata = metadata
+	const extra = mappingAt(values, 'metadata')
+	if (extra && Object.keys(extra).length > 0) {
+		skillMetadata.metadata = { ...extra }
 	}
 
 	return skillMetadata
 }
 
-function normalizeYamlScalar(value: string): string {
-	return value.replace(/^["']|["']$/g, '').trim()
-}
-
-/** A closing fence is a line of its own, not `---` wherever it appears. */
-const FRONTMATTER_FENCE = /^---[ \t]*$/m
-
-/**
- * YAML this reader does not implement, refused rather than mangled.
- *
- * The frontmatter reader here is a flat key/value splitter, and the
- * documented contract says "YAML frontmatter" with no restriction — so an
- * author has every reason to write a block scalar or a flow sequence, and
- * no reason to expect what happened next. A `description: >-` followed by
- * an indented paragraph produced the literal string `">-"`, which passed
- * validation and registered with no warning; the skill then existed and
- * was never selected, because its description said nothing. A
- * `[Read, Grep]` became that literal text and was interpolated straight
- * into the prompt.
- *
- * Refusing names the line and the file. That is worse for exactly one
- * skill — the one already silently broken — and better for everyone
- * looking for it.
- */
-const UNSUPPORTED_YAML = [
-	{ pattern: /^[>|][-+]?\s*$/, what: 'a block scalar (`>` or `|`)' },
-	{ pattern: /^\[.*\]$/, what: 'a flow sequence (`[a, b]`)' },
-	{ pattern: /^\{.*\}$/, what: 'a flow mapping (`{a: b}`)' },
-] as const
-
-function assertReadableScalar(key: string, rawValue: string, dirPath: string): void {
-	const value = rawValue.trim()
-	for (const { pattern, what } of UNSUPPORTED_YAML) {
-		if (!pattern.test(value)) continue
-		throw new Error(
-			`SKILL.md at "${dirPath}": "${key}" uses ${what}, which this reader does not support. Write it as a single-line value instead. Refusing rather than registering a skill whose "${key}" would read as ${JSON.stringify(value)}.`,
-		)
-	}
-}
-
 const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 
 function validateSkillName(name: string, dirPath: string): void {
@@ -191,10 +138,11 @@ export async function loadSkill(
 ): Promise<SkillLoadResult> {
 	const skillMdPath = join(dirPath, SKILL_FILENAME)
 	const raw = await readFile(skillMdPath, 'utf-8')
-	const parsed = parseSkillMd(raw, dirPath)
+	const parsed = parseFrontmatter(raw, sourceLabel(dirPath))
+	const metadata = toSkillMetadata(parsed, dirPath)
 
 	const skill: Skill = {
-		metadata: parsed.metadata,
+		metadata,
 		dirPath,
 	}
 
@@ -202,11 +150,11 @@ export async function loadSkill(
 		skill.body = parsed.body
 	}
 
-	const metadataTokens = estimateTokens(`${parsed.metadata.name}: ${parsed.metadata.description}`)
+	const metadataTokens = estimateTokens(`${metadata.name}: ${metadata.description}`)
 	const bodyTokens = skill.body ? estimateTokens(skill.body) : 0
 
 	logger.debug('Loaded skill', {
-		name: parsed.metadata.name,
+		name: metadata.name,
 		level,
 		tokens: metadataTokens + bodyTokens,
 	})