happyskills 0.50.0 → 0.52.0

package/CHANGELOG.md

@@ -7,6 +7,40 @@ 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
+
+- **`list --json` now splits unclaimed on-disk skills into `data.drafts[]` and `data.external[]`** (`cli/src/commands/list.js`, `cli/src/utils/skill_scanner.js`). Drafts are skills scaffolded by `init` — they have a HappySkills-shaped `skill.json` (non-empty `name`, valid-semver `version`, `type` of `"skill"` or `"kit"`) and a `SKILL.md`, but no entry in `skills-lock.json` yet because the user hasn't published. External skills are genuinely foreign — they have a `SKILL.md` but no manifest or a foreign-shaped one, and they require `convert` before they can be published. Each draft entry includes `{ name, description, version, type }`; external entries keep the existing `{ name, description }` shape. Human output gains a `draft (unpublished)` row label and a closing hint pointing at `happyskills release` so the principal sees what to do next without having to read the docs.
+- **`is_happyskills_shaped_manifest()` exported from `cli/src/utils/skill_scanner.js`** — small predicate that other call sites (e.g. `happyskills-publish`'s pre-flight) can use to classify a found-on-disk skill the same way `list` does.
+
+### Rationale
+
+Spec 260522-02: when a user scaffolded a skill with `npx happyskills init` and immediately asked an LLM agent to "publish it", the previous `list --json` output reported the skill under `data.external[]` — the same bucket used for genuinely-foreign skills. Routing skills (notably `happyskills-publish`) read this as "external, must `convert` first", inserted a redundant `convert` step into the happy path, and surfaced the words `external` and `convert` to a user who had created their skill with the official tool five minutes earlier. That violated the mission's principal-surface promise of "no unexplained jargon" and "consistency over novelty". The CLI fix is a data-layer split (`data.drafts[]` vs `data.external[]`) so every consumer — routing skills, human output, future tooling — can tell the two states apart at the source. The companion routing-skill fix lands in `happyskills-publish@0.5.0` (in the same monorepo change set), which now reads `data.drafts` and routes drafts straight to `release` without ever mentioning `convert` or `external` to the user.
+
 ## [0.50.0] - 2026-05-24
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.50.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,12 +135,12 @@ 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(', ')}`)
 	}
 	console.log()
-	print_hint(`Edit these files, then run ${code('happyskills publish')} to share.`)
+	print_hint(`Edit these files, then run ${code(`happyskills release ${final_name} --workspace <slug>`)} to publish.`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 module.exports = { run }

package/src/commands/list.js

@@ -51,16 +51,23 @@ const run = (args) => catch_errors('List failed', async () => {
 
 	const [, disk_skills] = await scan_skills_dir(base_dir)
 	const managed_names = new Set(managed_short_names)
-	const external_skills = (disk_skills || []).filter(s => !managed_names.has(s.name))
+	// Unclaimed skills (on disk, not in lock) split into two coherent buckets:
+	//   - drafts   → scaffolded by `init`, HappySkills-shaped skill.json present.
+	//                Publish/release pick these up directly — no `convert` needed.
+	//   - external → genuinely foreign (no skill.json, or foreign-shaped).
+	//                `convert` is the path to bring these into the managed set.
+	const unclaimed = (disk_skills || []).filter(s => !managed_names.has(s.name))
+	const draft_skills = unclaimed.filter(s => s.is_draft)
+	const external_skills = unclaimed.filter(s => !s.is_draft)
 
 	// Scan agent-specific dirs for skills placed directly in agent folders (not symlinked from .agents/skills/)
-	const all_known_names = new Set([...managed_names, ...external_skills.map(s => s.name)])
+	const all_known_names = new Set([...managed_names, ...draft_skills.map(s => s.name), ...external_skills.map(s => s.name)])
 	const [, agent_orphans] = await scan_agent_orphan_skills(AGENTS, is_global, project_root, all_known_names)
 	const orphan_skills = agent_orphans || []
 
-	if (managed_entries.length === 0 && external_skills.length === 0 && orphan_skills.length === 0) {
+	if (managed_entries.length === 0 && draft_skills.length === 0 && external_skills.length === 0 && orphan_skills.length === 0) {
 		if (args.flags.json) {
-			print_json({ data: { skills: {}, external: [], agent_orphans: [] } })
+			print_json({ data: { skills: {}, drafts: [], external: [], agent_orphans: [] } })
 			return
 		}
 		print_info('No skills installed.')
@@ -123,13 +130,19 @@ const run = (args) => catch_errors('List failed', async () => {
 			}
 			skills_map[name] = entry
 		}
+		const drafts = draft_skills.map(s => ({
+			name: s.name,
+			description: s.description || '',
+			version: s.version || null,
+			type: s.type || SKILL_TYPES.SKILL
+		}))
 		const external = external_skills.map(s => ({ name: s.name, description: s.description || '' }))
 		const agent_orphan_list = orphan_skills.map(s => ({
 			name: s.name,
 			description: s.description || '',
 			agents: s.agents
 		}))
-		print_json({ data: { skills: skills_map, external, agent_orphans: agent_orphan_list } })
+		print_json({ data: { skills: skills_map, drafts, external, agent_orphans: agent_orphan_list } })
 		return
 	}
 
@@ -153,6 +166,11 @@ const run = (args) => catch_errors('List failed', async () => {
 		rows.push([display_name, data.version, source, status_label, enabled_label])
 	}
 
+	for (const s of draft_skills) {
+		const type_label = s.type === SKILL_TYPES.KIT ? `${s.name} [kit]` : s.name
+		rows.push([type_label, s.version || '-', 'draft', 'unpublished', '-'])
+	}
+
 	for (const s of external_skills) {
 		rows.push([s.name, '-', 'external', 'installed', '-'])
 	}
@@ -175,6 +193,10 @@ const run = (args) => catch_errors('List failed', async () => {
 		console.log()
 		print_info(`${ahead_count} skill(s) ahead of lock — bumped locally, not yet published. Run publish when ready.`)
 	}
+	if (draft_skills.length > 0) {
+		console.log()
+		print_info(`${draft_skills.length} draft(s) ready to publish — run ${code('happyskills release <name>')} to ship.`)
+	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 module.exports = { run }

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/integration/cli.test.js

@@ -379,7 +379,7 @@ describe('CLI — --json: success responses use { data } envelope', () => {
 // ─── --json flag: existing commands use { data } envelope ─────────────────────
 
 describe('CLI — --json: existing json commands now use { data } envelope', () => {
-	it('list --json returns { data: { skills, external } }', () => {
+	it('list --json returns { data: { skills, drafts, external } }', () => {
 		// Run in a temp dir with no lock file — produces empty result
 		const tmp = make_tmp()
 		try {
@@ -388,14 +388,51 @@ describe('CLI — --json: existing json commands now use { data } envelope', ()
 			const out = parse_json_output(stdout, 'list --json empty')
 			assert.ok('data' in out, 'should have top-level "data" key')
 			assert.ok('skills' in out.data, 'data.skills should exist')
+			assert.ok('drafts' in out.data, 'data.drafts should exist')
 			assert.ok('external' in out.data, 'data.external should exist')
 			assert.ok(typeof out.data.skills === 'object' && !Array.isArray(out.data.skills))
+			assert.ok(Array.isArray(out.data.drafts))
 			assert.ok(Array.isArray(out.data.external))
 		} finally {
 			fs.rmSync(tmp, { recursive: true, force: true })
 		}
 	})
 
+	it('list --json classifies init-scaffolded skills as drafts, foreign-shaped ones as external', () => {
+		// Two on-disk skills, no lock file:
+		//   - "my-draft"   has a HappySkills-shaped skill.json (init-style)
+		//   - "my-foreign" has only SKILL.md (foreign / hand-rolled)
+		const tmp = make_tmp()
+		try {
+			const draft_dir = path.join(tmp, '.agents', 'skills', 'my-draft')
+			fs.mkdirSync(draft_dir, { recursive: true })
+			fs.writeFileSync(path.join(draft_dir, 'SKILL.md'), '---\nname: my-draft\ndescription: a draft skill\n---\n\n# my-draft\n')
+			fs.writeFileSync(path.join(draft_dir, 'skill.json'), JSON.stringify({
+				name: 'my-draft',
+				version: '0.1.0',
+				type: 'skill',
+				description: '',
+				keywords: [],
+				dependencies: {}
+			}))
+
+			const foreign_dir = path.join(tmp, '.agents', 'skills', 'my-foreign')
+			fs.mkdirSync(foreign_dir, { recursive: true })
+			fs.writeFileSync(path.join(foreign_dir, 'SKILL.md'), '---\nname: my-foreign\ndescription: a foreign skill\n---\n\n# my-foreign\n')
+
+			const { stdout, code } = run(['list', '--json'], {}, { cwd: tmp })
+			assert.strictEqual(code, 0)
+			const out = parse_json_output(stdout, 'list --json mixed')
+			assert.strictEqual(out.data.drafts.length, 1, 'should have exactly one draft')
+			assert.strictEqual(out.data.drafts[0].name, 'my-draft')
+			assert.strictEqual(out.data.drafts[0].version, '0.1.0')
+			assert.strictEqual(out.data.external.length, 1, 'should have exactly one external')
+			assert.strictEqual(out.data.external[0].name, 'my-foreign')
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
 	it('search --json usage error returns { error } not raw text', () => {
 		const { stdout, code } = run(['search', '--json'])
 		assert.strictEqual(code, 2)

package/src/utils/skill_scanner.js

@@ -1,9 +1,25 @@
 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_MD, README_MD, SKILL_TYPES } = require('../constants')
 
 const SKIP_ENTRIES = new Set(['.tmp', '.DS_Store', '.install.lock'])
 
+// A disk-resident, unclaimed skill is a "draft" when it has a HappySkills-shaped
+// skill.json next to its SKILL.md — i.e. the file `init` already produced.
+// "HappySkills-shaped" means: a non-empty `name`, a valid-semver `version`, and
+// a `type` of "skill" or "kit". This is the minimum surface `release`/`publish`
+// can pick up on a no-lock-entry first publish without an intermediate `convert`.
+const is_happyskills_shaped_manifest = (manifest) => {
+	if (!manifest || typeof manifest !== 'object') return false
+	if (typeof manifest.name !== 'string' || !manifest.name.trim()) return false
+	if (!valid_semver(manifest.version)) return false
+	const t = manifest.type
+	if (t && t !== SKILL_TYPES.SKILL && t !== SKILL_TYPES.KIT) return false
+	return true
+}
+
 const parse_frontmatter = (content) => {
 	const match = content.match(/^---\n([\s\S]*?)\n---/)
 	if (!match) return null
@@ -32,7 +48,39 @@ 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')
+
+		// 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 {
+			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
+		}
+
+		// Skill branch: SKILL.md is required (frontmatter is the discovery signal).
+		const skill_md_path = path.join(dir, SKILL_MD)
 
 		let content
 		try {
@@ -44,9 +92,14 @@ const scan_skills_dir = (base_dir) => catch_errors('Failed to scan skills direct
 		const frontmatter = parse_frontmatter(content)
 		if (!frontmatter || !frontmatter.name) continue
 
+		const is_draft = is_happyskills_shaped_manifest(manifest)
+
 		skills.push({
 			name: frontmatter.name,
-			description: frontmatter.description || ''
+			description: frontmatter.description || '',
+			is_draft,
+			version: is_draft ? manifest.version : null,
+			type: is_draft ? (manifest.type || SKILL_TYPES.SKILL) : null
 		})
 	}
 
@@ -129,4 +182,4 @@ const scan_agent_orphan_skills = (agents, is_global, project_root, known_names)
 	return [...by_name.values()]
 })
 
-module.exports = { scan_skills_dir, scan_agent_orphan_skills, parse_frontmatter }
+module.exports = { scan_skills_dir, scan_agent_orphan_skills, parse_frontmatter, is_happyskills_shaped_manifest }

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 }