happyskills 0.51.0 → 0.52.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.52.0] - 2026-05-25
+
+### Added
+
+- **Schema-driven SKILL.md frontmatter validator with line-pinpointed, auto-correctable errors** (`cli/src/validation/frontmatter_schema.js`, `cli/src/utils/yaml_frontmatter.js`, rewritten `cli/src/validation/skill_md_rules.js`). Every known frontmatter field is now declared once in a single schema (`name`, `description`, `argument-hint`, `compatibility`, `allowed-tools`, `disable-model-invocation`, `user-invocable`, `context`, `agent`, `keywords`) with its accepted YAML types and constraints. One generic pass type-checks every field, applies field-specific rules (max length, pattern, enum, forbidden chars), and flags unknown fields with a Levenshtein-1 did-you-mean (typos like `argument_hint` → `argument-hint`). Unknown fields that aren't near a known one pass silently for forward-compat with future Anthropic additions.
+- **Typed YAML frontmatter parser** — a new `parse_typed()` returns each field with its parsed value AND its YAML-inferred type (`string` / `array` / `object` / `boolean` / `null` / `number` / `block_scalar`), plus the 1-based file-line number, the raw text, and a `quoted` marker (`plain` / `single` / `double`). The legacy plain-string `parse_frontmatter` is preserved for downstream callers (`convert`, `scan_skills_dir`). This is what lets the validator see what Claude Code's stricter loader sees — e.g. `argument-hint: [foo]` parsing as `["foo"]` rather than `"[foo]"`.
+- **Auto-correct contract on every frontmatter error**. Each error result now ships, in addition to `file` + `field` + `rule` + `severity` + `message`: a `line` (file line, not body line — matches `head -n N`), an `expected` and `actual` for type mismatches, a `character` + `character_name` + `char_index` for forbidden-char errors, a `suggestion` for did-you-mean warnings, and — where applicable — a literal `fix` line the caller (LLM or human) can write back verbatim (e.g. `fix: 'argument-hint: "[question or topic]"'`). Every error message also leads with `SKILL.md line N: ...` so the file-line locator is in the prose too. Locked in by a new `error contract for LLM consumers` test suite.
+
+### Changed
+
+- **Frontmatter type mismatches on known string fields are now hard errors at the publish gate**, fixing the bug in which `argument-hint: [question or topic]` (no quotes) shipped as the SKILL.md of `init-context` and several other authored-in-place skills. YAML parses the bracketed form as a flow sequence (an array), so Claude Code's loader silently dropped or warned about the skill. The new validator catches this class deterministically — bracket-bug (`[...]` → array), brace-bug (`{...}` → object), boolean-as-string (`disable-model-invocation: maybe`), forbidden-char-in-known-field (e.g. unquoted colon in `description`) — and emits an actionable fix line. Promoted from warning → error: `disable-model-invocation` / `user-invocable` with a non-boolean value (was a soft warning; the loader treats it as a strict YAML boolean, so a non-boolean was always a contract violation). Bug-side fix: `init-context/SKILL.md` `argument-hint` re-quoted.
+- **Kits now use `README.md` instead of a frontmatter-less `SKILL.md`** (`cli/src/commands/init.js`, `cli/src/constants.js`, `cli/src/utils/skill_scanner.js`, `cli/src/validation/skill_md_rules.js`). The previous design kept kits invisible to Claude Code by writing a `SKILL.md` with no YAML frontmatter — Claude silently ignored it, but Codex and Gemini correctly treat a frontmatter-less `SKILL.md` as a malformed skill and emit warnings on every load. Splitting kits onto `README.md` removes the warning class entirely: every agent runtime ignores `README.md`, no runtime-specific exemption is required, and the kit's invisibility is now a structural property (no `SKILL.md` present) instead of a runtime trick.
+  - `init --kit` now writes `README.md` and lists it in `files_created`. Help text updated.
+  - `scan_skills_dir` now reads `skill.json` first; for a kit manifest, it requires `README.md` and derives identity from `skill.json` (kits have no `SKILL.md` frontmatter to read `name` / `description` from). Regular skills continue to surface via `SKILL.md` frontmatter, unchanged.
+  - `validate` for kits requires a `README.md` and rejects any `SKILL.md` found inside a kit directory — its presence would re-expose the kit to agent auto-invocation and re-trigger the Codex/Gemini warnings the new layout exists to avoid.
+  - `README_MD = 'README.md'` added to `cli/src/constants.js`.
+
+### Rationale
+
+The frontmatter-less `SKILL.md` hack worked in Claude Code only — it relied on Claude silently dropping skills with no `description` field. Codex and Gemini, which faithfully implement the public skill spec, treat the same file as malformed and warn on every session. That conflicts with the mission's multi-agent posture (skills must work across Claude Code, Cursor, Windsurf, Codex, etc.) and the principal-surface promise of "no unexplained jargon" (the user sees warnings about their kit that they can't act on). Switching to `README.md` aligns the kit format with primitives every tool already understands, and turns invisibility into a structural property of the kit folder rather than a runtime-specific exemption.
+
+Existing kits on the registry (a small handful at the time of writing) are migrated by hand — there is no auto-migration. Once republished with `README.md`, future installs land the kit in the new shape.
+
 ## [0.51.0] - 2026-05-25
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.51.0",
+	"version": "0.52.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/commands/init.js

@@ -4,7 +4,7 @@ const { write_manifest } = require('../manifest/writer')
 const { write_file, file_exists, ensure_dir } = require('../utils/fs')
 const { print_success, print_error, print_help, print_hint, print_json, print_info, print_warn, code } = require('../ui/output')
 const { exit_with_error, CliError, UsageError } = require('../utils/errors')
-const { SKILL_JSON, SKILL_MD, EXIT_CODES, SKILL_TYPES, KIT_PREFIX } = require('../constants')
+const { SKILL_JSON, SKILL_MD, README_MD, EXIT_CODES, SKILL_TYPES, KIT_PREFIX } = require('../constants')
 const { find_project_root, skills_dir } = require('../config/paths')
 const { resolve_agents, link_to_agents } = require('../agents')
 
@@ -15,6 +15,8 @@ Scaffold a new skill in .agents/skills/<name>/.
 Creates:
   .agents/skills/<name>/skill.json    Skill manifest (name, version, deps)
   .agents/skills/<name>/SKILL.md      Skill instructions for AI agents
+                                      (kits get README.md instead — kits
+                                      are not invocable by agents)
 
 Arguments:
   name          Skill name (required, e.g., my-deploy-skill)
@@ -97,12 +99,17 @@ const run = (args) => catch_errors('Init failed', async () => {
 
 	const files_created = [SKILL_JSON]
 
-	const [, md_exists] = await file_exists(path.join(dir, SKILL_MD))
+	// Kits use README.md (no agent-invocable content); skills use SKILL.md.
+	// Splitting the file name is what keeps kits invisible to every agent
+	// runtime without relying on a missing-frontmatter trick that triggers
+	// warnings in Codex/Gemini.
+	const md_file = is_kit ? README_MD : SKILL_MD
+	const [, md_exists] = await file_exists(path.join(dir, md_file))
 	if (!md_exists) {
 		const md_content = is_kit ? create_kit_md(final_name) : create_skill_md(final_name)
-		const [md_err] = await write_file(path.join(dir, SKILL_MD), md_content)
-		if (md_err) throw e('Failed to write SKILL.md', md_err)
-		files_created.push(SKILL_MD)
+		const [md_err] = await write_file(path.join(dir, md_file), md_content)
+		if (md_err) throw e(`Failed to write ${md_file}`, md_err)
+		files_created.push(md_file)
 	}
 
 	const label = is_kit ? 'kit' : 'skill'
@@ -128,7 +135,7 @@ const run = (args) => catch_errors('Init failed', async () => {
 
 	print_success(`Initialized ${label} "${final_name}" at ${dir}`)
 	console.log(`  ${SKILL_JSON}  — manifest`)
-	console.log(`  ${SKILL_MD}    — ${is_kit ? 'kit description' : 'instructions'}`)
+	console.log(`  ${md_file}    — ${is_kit ? 'kit description' : 'instructions'}`)
 	if (linked_agents.length > 0) {
 		print_info(`Linked to: ${agents_result.agents.map(a => a.display_name).join(', ')}`)
 	}

package/src/constants.js

@@ -20,6 +20,7 @@ const LOCK_VERSION = 2
 
 const SKILL_JSON = 'skill.json'
 const SKILL_MD = 'SKILL.md'
+const README_MD = 'README.md'
 const LOCK_FILE = 'skills-lock.json'
 const INSTALL_LOCK = '.install.lock'
 
@@ -91,6 +92,7 @@ module.exports = {
 	LOCK_VERSION,
 	SKILL_JSON,
 	SKILL_MD,
+	README_MD,
 	LOCK_FILE,
 	INSTALL_LOCK,
 	COMMAND_ALIASES,

package/src/utils/skill_scanner.js

@@ -2,7 +2,7 @@ const fs = require('fs')
 const path = require('path')
 const { error: { catch_errors } } = require('puffy-core')
 const { valid: valid_semver } = require('./semver')
-const { SKILL_JSON, SKILL_TYPES } = require('../constants')
+const { SKILL_JSON, SKILL_MD, README_MD, SKILL_TYPES } = require('../constants')
 
 const SKIP_ENTRIES = new Set(['.tmp', '.DS_Store', '.install.lock'])
 
@@ -48,29 +48,50 @@ const scan_skills_dir = (base_dir) => catch_errors('Failed to scan skills direct
 		if (entry.name.startsWith('.') || SKIP_ENTRIES.has(entry.name)) continue
 
 		const dir = path.join(base_dir, entry.name)
-		const skill_md_path = path.join(dir, 'SKILL.md')
 
-		let content
+		// Read skill.json first — it's the authoritative manifest. Kits have
+		// no SKILL.md at all (only README.md) so the manifest is the only
+		// reliable name/description source for them.
+		let manifest = null
 		try {
-			content = await fs.promises.readFile(skill_md_path, 'utf-8')
+			const raw = await fs.promises.readFile(path.join(dir, SKILL_JSON), 'utf-8')
+			manifest = JSON.parse(raw)
 		} catch {
+			// No skill.json — could still be a foreign skill with a frontmatter SKILL.md. manifest stays null.
+		}
+
+		const is_kit_manifest = manifest && manifest.type === SKILL_TYPES.KIT
+
+		if (is_kit_manifest) {
+			// Kit branch: require README.md presence, derive identity from skill.json.
+			let readme_ok = true
+			try { await fs.promises.access(path.join(dir, README_MD)) } catch { readme_ok = false }
+			if (!readme_ok) continue
+
+			const is_draft = is_happyskills_shaped_manifest(manifest)
+			skills.push({
+				name: manifest.name,
+				description: manifest.description || '',
+				is_draft,
+				version: is_draft ? manifest.version : null,
+				type: SKILL_TYPES.KIT
+			})
 			continue
 		}
 
-		const frontmatter = parse_frontmatter(content)
-		if (!frontmatter || !frontmatter.name) continue
+		// Skill branch: SKILL.md is required (frontmatter is the discovery signal).
+		const skill_md_path = path.join(dir, SKILL_MD)
 
-		// Detect whether this skill has a HappySkills-shaped manifest. If yes,
-		// callers can classify it as a "draft" (scaffolded by `init`, not yet
-		// claimed in the lock) rather than "external" (genuinely foreign).
-		let manifest = null
+		let content
 		try {
-			const raw = await fs.promises.readFile(path.join(dir, SKILL_JSON), 'utf-8')
-			manifest = JSON.parse(raw)
+			content = await fs.promises.readFile(skill_md_path, 'utf-8')
 		} catch {
-			// No skill.json — genuinely external. manifest stays null.
+			continue
 		}
 
+		const frontmatter = parse_frontmatter(content)
+		if (!frontmatter || !frontmatter.name) continue
+
 		const is_draft = is_happyskills_shaped_manifest(manifest)
 
 		skills.push({

package/src/utils/skill_scanner.test.js

@@ -0,0 +1,61 @@
+const { describe, it, before, after } = require('node:test')
+const assert = require('node:assert')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { scan_skills_dir } = require('./skill_scanner')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'scanner-'))
+
+const write_skill = (root, name, files) => {
+	const dir = path.join(root, name)
+	fs.mkdirSync(dir, { recursive: true })
+	for (const [file, content] of Object.entries(files)) {
+		fs.writeFileSync(path.join(dir, file), content)
+	}
+	return dir
+}
+
+describe('scan_skills_dir — kit drafts detected via README.md', () => {
+	let tmp
+
+	before(() => { tmp = make_tmp() })
+	after(() => { fs.rmSync(tmp, { recursive: true, force: true }) })
+
+	it('surfaces a kit (skill.json + README.md, no SKILL.md) as a draft', async () => {
+		write_skill(tmp, '_kit-demo', {
+			'skill.json': JSON.stringify({ name: '_kit-demo', version: '0.1.0', type: 'kit', description: 'A demo kit' }),
+			'README.md': '# _kit-demo\n\nThis is a kit.'
+		})
+		const [err, skills] = await scan_skills_dir(tmp)
+		assert.ifError(err)
+		const kit = skills.find(s => s.name === '_kit-demo')
+		assert.ok(kit, 'kit should be discovered')
+		assert.strictEqual(kit.type, 'kit')
+		assert.strictEqual(kit.is_draft, true)
+		assert.strictEqual(kit.version, '0.1.0')
+		assert.strictEqual(kit.description, 'A demo kit')
+	})
+
+	it('skips a kit folder that has skill.json but no README.md', async () => {
+		write_skill(tmp, '_kit-no-readme', {
+			'skill.json': JSON.stringify({ name: '_kit-no-readme', version: '0.1.0', type: 'kit' })
+		})
+		const [err, skills] = await scan_skills_dir(tmp)
+		assert.ifError(err)
+		assert.ok(!skills.some(s => s.name === '_kit-no-readme'))
+	})
+
+	it('still surfaces a regular skill via SKILL.md frontmatter (unchanged)', async () => {
+		write_skill(tmp, 'plain', {
+			'skill.json': JSON.stringify({ name: 'plain', version: '0.1.0', type: 'skill' }),
+			'SKILL.md': '---\nname: plain\ndescription: A plain skill\n---\n\n# plain'
+		})
+		const [err, skills] = await scan_skills_dir(tmp)
+		assert.ifError(err)
+		const s = skills.find(x => x.name === 'plain')
+		assert.ok(s)
+		assert.strictEqual(s.type, 'skill')
+		assert.strictEqual(s.is_draft, true)
+	})
+})

package/src/utils/yaml_frontmatter.js

@@ -0,0 +1,175 @@
+// Typed YAML frontmatter parser.
+//
+// Returns each field with its parsed value AND its YAML-inferred type, so
+// validators can detect type mismatches (e.g. `argument-hint: [foo]` parsing
+// as an array when a string was expected). Mirrors how a real YAML loader
+// (and Claude Code's skill loader) interprets unquoted scalars.
+//
+// Scope: single-line scalars and flow collections in frontmatter only.
+// Block scalars (|, >) and multi-line constructs are flagged as such; we do
+// not assemble their multi-line bodies — frontmatter values should be single
+// line, and a block scalar in frontmatter is itself a smell worth surfacing.
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/
+
+const NUMBER_RE = /^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?$/
+const INT_RE = /^-?(0|[1-9][0-9]*)$/
+
+// Parse a scalar value from raw YAML text (no leading/trailing whitespace).
+// Returns { value, type } where type ∈ string|array|object|boolean|null|number|block_scalar.
+const parse_scalar = (raw) => {
+	if (raw === '' || raw === '~' || raw === 'null' || raw === 'Null' || raw === 'NULL')
+		return { value: null, type: 'null' }
+
+	if (raw === 'true' || raw === 'True' || raw === 'TRUE')
+		return { value: true, type: 'boolean' }
+	if (raw === 'false' || raw === 'False' || raw === 'FALSE')
+		return { value: false, type: 'boolean' }
+
+	if (raw[0] === '|' || raw[0] === '>')
+		return { value: raw, type: 'block_scalar' }
+
+	if (raw[0] === '"' && raw[raw.length - 1] === '"' && raw.length >= 2)
+		return { value: unescape_double(raw.slice(1, -1)), type: 'string', quoted: 'double' }
+
+	if (raw[0] === "'" && raw[raw.length - 1] === "'" && raw.length >= 2)
+		return { value: raw.slice(1, -1).replace(/''/g, "'"), type: 'string', quoted: 'single' }
+
+	if (raw[0] === '[' && raw[raw.length - 1] === ']')
+		return { value: parse_flow_sequence(raw.slice(1, -1)), type: 'array' }
+
+	if (raw[0] === '{' && raw[raw.length - 1] === '}')
+		return { value: parse_flow_mapping(raw.slice(1, -1)), type: 'object' }
+
+	if (NUMBER_RE.test(raw)) {
+		const n = Number(raw)
+		if (Number.isFinite(n)) return { value: n, type: 'number', is_int: INT_RE.test(raw) }
+	}
+
+	return { value: raw, type: 'string', quoted: 'plain' }
+}
+
+const unescape_double = (s) => s.replace(/\\(["\\nrt])/g, (_, c) => ({ n: '\n', r: '\r', t: '\t', '"': '"', '\\': '\\' })[c])
+
+const split_flow = (body) => {
+	const items = []
+	let depth = 0
+	let in_dq = false
+	let in_sq = false
+	let start = 0
+	for (let i = 0; i < body.length; i++) {
+		const c = body[i]
+		if (in_dq) { if (c === '\\') i++; else if (c === '"') in_dq = false; continue }
+		if (in_sq) { if (c === "'") in_sq = false; continue }
+		if (c === '"') { in_dq = true; continue }
+		if (c === "'") { in_sq = true; continue }
+		if (c === '[' || c === '{') depth++
+		else if (c === ']' || c === '}') depth--
+		else if (c === ',' && depth === 0) { items.push(body.slice(start, i).trim()); start = i + 1 }
+	}
+	const tail = body.slice(start).trim()
+	if (tail !== '' || items.length > 0) items.push(tail)
+	return items
+}
+
+const parse_flow_sequence = (body) => split_flow(body).filter(s => s !== '').map(s => parse_scalar(s).value)
+
+const parse_flow_mapping = (body) => {
+	const out = {}
+	for (const pair of split_flow(body)) {
+		if (pair === '') continue
+		const colon = find_top_level_colon(pair)
+		if (colon === -1) { out[pair] = null; continue }
+		const k = pair.slice(0, colon).trim()
+		const v = pair.slice(colon + 1).trim()
+		out[parse_scalar(k).value] = parse_scalar(v).value
+	}
+	return out
+}
+
+// Find the first ':' that is at top level (not inside quotes or flow brackets).
+const find_top_level_colon = (line) => {
+	let in_dq = false, in_sq = false, depth = 0
+	for (let i = 0; i < line.length; i++) {
+		const c = line[i]
+		if (in_dq) { if (c === '\\') i++; else if (c === '"') in_dq = false; continue }
+		if (in_sq) { if (c === "'") in_sq = false; continue }
+		if (c === '"') { in_dq = true; continue }
+		if (c === "'") { in_sq = true; continue }
+		if (c === '[' || c === '{') { depth++; continue }
+		if (c === ']' || c === '}') { depth--; continue }
+		if (c === ':' && depth === 0) return i
+	}
+	return -1
+}
+
+// Strip a trailing unquoted YAML comment from a scalar line (everything after ' #').
+// Comments inside quotes/brackets are preserved.
+const strip_trailing_comment = (s) => {
+	let in_dq = false, in_sq = false, depth = 0
+	for (let i = 0; i < s.length; i++) {
+		const c = s[i]
+		if (in_dq) { if (c === '\\') i++; else if (c === '"') in_dq = false; continue }
+		if (in_sq) { if (c === "'") in_sq = false; continue }
+		if (c === '"') { in_dq = true; continue }
+		if (c === "'") { in_sq = true; continue }
+		if (c === '[' || c === '{') { depth++; continue }
+		if (c === ']' || c === '}') { depth--; continue }
+		if (c === '#' && depth === 0 && (i === 0 || /\s/.test(s[i - 1]))) return s.slice(0, i).trimEnd()
+	}
+	return s
+}
+
+// Top-level: parse a frontmatter block into { fields, errors, raw }.
+// `fields` maps key → { value, type, raw, line, quoted? }.
+//
+// `line` is the 1-based line number IN THE SOURCE FILE (not in the body) —
+// the opening `---` is line 1, the first key/value lives on line 2, and so
+// on. This makes error messages directly actionable: "SKILL.md line 4" lines
+// up with what an editor or `head -n 4` would show.
+const parse_typed = (content) => {
+	const match = content.match(FRONTMATTER_RE)
+	if (!match) return null
+
+	const body = match[1]
+	const lines = body.split(/\r?\n/)
+	const fields = {}
+	const errors = []
+
+	// Body line 0 ⇒ file line 2 (file line 1 is the opening `---`).
+	const file_line = (i) => i + 2
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]
+		const trimmed = line.trim()
+		if (trimmed === '' || trimmed.startsWith('#')) continue
+
+		// Block scalars and continuation lines are not supported in this parser.
+		// A line with no top-level ':' is treated as a structural error.
+		const colon = find_top_level_colon(line)
+		if (colon === -1) {
+			errors.push({ line: file_line(i), message: `Cannot parse line (no key): ${trimmed}` })
+			continue
+		}
+
+		const key = line.slice(0, colon).trim()
+		if (!key) {
+			errors.push({ line: file_line(i), message: 'Empty key' })
+			continue
+		}
+
+		const value_text = strip_trailing_comment(line.slice(colon + 1).trim())
+		const parsed = parse_scalar(value_text)
+		fields[key] = {
+			value: parsed.value,
+			type: parsed.type,
+			raw: value_text,
+			line: file_line(i),
+			...(parsed.quoted ? { quoted: parsed.quoted } : {})
+		}
+	}
+
+	return { fields, errors, raw: body }
+}
+
+module.exports = { parse_typed, parse_scalar }

package/src/utils/yaml_frontmatter.test.js

@@ -0,0 +1,110 @@
+const { test } = require('node:test')
+const assert = require('node:assert/strict')
+const { parse_typed, parse_scalar } = require('./yaml_frontmatter')
+
+const wrap = (body) => `---\n${body}\n---\n`
+
+test('parse_scalar: empty / null literals', () => {
+	assert.deepEqual(parse_scalar(''), { value: null, type: 'null' })
+	assert.deepEqual(parse_scalar('null'), { value: null, type: 'null' })
+	assert.deepEqual(parse_scalar('~'), { value: null, type: 'null' })
+})
+
+test('parse_scalar: booleans', () => {
+	assert.equal(parse_scalar('true').value, true)
+	assert.equal(parse_scalar('true').type, 'boolean')
+	assert.equal(parse_scalar('False').value, false)
+})
+
+test('parse_scalar: numbers', () => {
+	assert.deepEqual(parse_scalar('42'), { value: 42, type: 'number', is_int: true })
+	assert.equal(parse_scalar('1.5').value, 1.5)
+})
+
+test('parse_scalar: plain string', () => {
+	assert.deepEqual(parse_scalar('hello world'), { value: 'hello world', type: 'string', quoted: 'plain' })
+})
+
+test('parse_scalar: double-quoted string', () => {
+	const r = parse_scalar('"[question or topic]"')
+	assert.equal(r.value, '[question or topic]')
+	assert.equal(r.type, 'string')
+	assert.equal(r.quoted, 'double')
+})
+
+test('parse_scalar: single-quoted string', () => {
+	const r = parse_scalar("'foo bar'")
+	assert.equal(r.value, 'foo bar')
+	assert.equal(r.type, 'string')
+	assert.equal(r.quoted, 'single')
+})
+
+test('parse_scalar: unquoted brackets parse as array (the bug)', () => {
+	const r = parse_scalar('[question or topic]')
+	assert.equal(r.type, 'array')
+	assert.deepEqual(r.value, ['question or topic'])
+})
+
+test('parse_scalar: unquoted brace-delimited parses as object', () => {
+	const r = parse_scalar('{a: 1, b: 2}')
+	assert.equal(r.type, 'object')
+	assert.deepEqual(r.value, { a: 1, b: 2 })
+})
+
+test('parse_scalar: bracketed list with multiple items', () => {
+	const r = parse_scalar('[a, b, c]')
+	assert.deepEqual(r.value, ['a', 'b', 'c'])
+})
+
+test('parse_typed: full frontmatter with the bug', () => {
+	const content = wrap([
+		'name: init-context',
+		'description: ProjectMemory — Load project docs.',
+		'argument-hint: [question or topic]'
+	].join('\n'))
+
+	const parsed = parse_typed(content)
+	assert.equal(parsed.fields.name.type, 'string')
+	assert.equal(parsed.fields.description.type, 'string')
+	assert.equal(parsed.fields['argument-hint'].type, 'array')
+	assert.deepEqual(parsed.fields['argument-hint'].value, ['question or topic'])
+})
+
+test('parse_typed: quoted form is a string', () => {
+	const content = wrap('argument-hint: "[question or topic]"')
+	const parsed = parse_typed(content)
+	assert.equal(parsed.fields['argument-hint'].type, 'string')
+	assert.equal(parsed.fields['argument-hint'].value, '[question or topic]')
+	assert.equal(parsed.fields['argument-hint'].quoted, 'double')
+})
+
+test('parse_typed: trailing comment is stripped from plain scalars', () => {
+	const content = wrap('name: my-skill # this is a comment')
+	const parsed = parse_typed(content)
+	assert.equal(parsed.fields.name.value, 'my-skill')
+})
+
+test('parse_typed: # inside a quoted string is preserved', () => {
+	const content = wrap('description: "foo # bar"')
+	const parsed = parse_typed(content)
+	assert.equal(parsed.fields.description.value, 'foo # bar')
+})
+
+test('parse_typed: top-level colon inside unquoted value (deploy: production)', () => {
+	// `description: deploy: production` — first colon splits the key, the
+	// second one stays inside the value as a literal character.
+	const content = wrap('description: deploy: production')
+	const parsed = parse_typed(content)
+	assert.equal(parsed.fields.description.type, 'string')
+	assert.equal(parsed.fields.description.value, 'deploy: production')
+})
+
+test('parse_typed: returns null when no frontmatter block', () => {
+	assert.equal(parse_typed('no frontmatter here'), null)
+})
+
+test('parse_typed: surfaces structural errors for malformed lines', () => {
+	const content = wrap('name: ok\nthis line has no colon')
+	const parsed = parse_typed(content)
+	assert.ok(parsed.errors.length >= 1)
+})

package/src/validation/frontmatter_schema.js

@@ -0,0 +1,107 @@
+// Schema describing every known SKILL.md frontmatter field.
+//
+// Why a schema (and not per-field functions): bugs like the unquoted
+// `argument-hint: [foo]` (which YAML parses as an array, not a string) are
+// type mismatches. A single generic checker that compares each field's
+// parsed YAML type against a declared `type` catches the whole class in one
+// pass — and every new field gets the check by adding one row, not a new
+// branch.
+//
+// Unknown fields are NOT rejected. Anthropic may add new frontmatter fields
+// over time; we warn only when an unknown key looks like a typo of a known
+// one (Levenshtein distance 1).
+
+const NAME_PATTERN = /^[a-z][a-z0-9-]*$/
+
+// Forbidden characters: YAML structural metacharacters that, even when they
+// pass our parser as plain strings, break Claude Code's stricter loader or
+// the skill discovery layer. See docs/gotchas/skills.md § 1.2.
+const FORBIDDEN_CHARS = {
+	';': 'semicolon', ':': 'colon', '#': 'hash', '{': 'left brace', '}': 'right brace',
+	'[': 'left bracket', ']': 'right bracket', "'": 'single quote', '"': 'double quote',
+	'!': 'exclamation', '&': 'ampersand', '*': 'asterisk', '%': 'percent', '|': 'pipe', '>': 'greater-than'
+}
+
+// Type categories accepted by the validator. Multi-type fields list each
+// permitted type — e.g. `allowed-tools` can be a YAML string or a YAML list.
+const FRONTMATTER_SCHEMA = {
+	name: {
+		types: ['string'],
+		required: true,
+		pattern: NAME_PATTERN,
+		pattern_message: 'must match /^[a-z][a-z0-9-]*$/',
+		max_length: 64,
+		non_empty: true,
+		matches_dir: true
+	},
+	description: {
+		types: ['string'],
+		required: true,
+		non_empty: true,
+		max_length: 1024,
+		forbidden_chars: true
+	},
+	'argument-hint': {
+		types: ['string'],
+		forbidden_chars_in_plain_only: true
+	},
+	compatibility: {
+		types: ['string'],
+		max_length: 500,
+		forbidden_chars: true
+	},
+	'allowed-tools': {
+		types: ['string', 'array']
+	},
+	'disable-model-invocation': {
+		types: ['boolean']
+	},
+	'user-invocable': {
+		types: ['boolean']
+	},
+	context: {
+		types: ['string'],
+		enum: ['fork']
+	},
+	agent: {
+		types: ['string']
+	},
+	keywords: {
+		types: ['string', 'array']
+	}
+}
+
+const KNOWN_FIELDS = Object.keys(FRONTMATTER_SCHEMA)
+
+// Cheap Levenshtein for did-you-mean. Bounded at distance 2.
+const levenshtein = (a, b) => {
+	if (a === b) return 0
+	if (Math.abs(a.length - b.length) > 2) return 3
+	const m = a.length, n = b.length
+	const prev = Array(n + 1).fill(0).map((_, i) => i)
+	const cur = Array(n + 1).fill(0)
+	for (let i = 1; i <= m; i++) {
+		cur[0] = i
+		for (let j = 1; j <= n; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1
+			cur[j] = Math.min(cur[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost)
+		}
+		for (let j = 0; j <= n; j++) prev[j] = cur[j]
+	}
+	return prev[n]
+}
+
+const did_you_mean = (key) => {
+	for (const known of KNOWN_FIELDS) {
+		if (levenshtein(key, known) === 1) return known
+	}
+	return null
+}
+
+module.exports = {
+	FRONTMATTER_SCHEMA,
+	FORBIDDEN_CHARS,
+	KNOWN_FIELDS,
+	NAME_PATTERN,
+	did_you_mean
+}