happyskills 0.50.0 → 0.52.0

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
+}

package/src/validation/skill_md_rules.js

@@ -2,84 +2,231 @@ const path = require('path')
 const { error: { catch_errors } } = require('puffy-core')
 const { file_exists, read_file } = require('../utils/fs')
 const { parse_frontmatter } = require('../utils/skill_scanner')
-const { SKILL_MD, SKILL_TYPES } = require('../constants')
+const { parse_typed } = require('../utils/yaml_frontmatter')
+const { SKILL_MD, README_MD, SKILL_TYPES } = require('../constants')
+const {
+	FRONTMATTER_SCHEMA,
+	FORBIDDEN_CHARS,
+	KNOWN_FIELDS,
+	did_you_mean
+} = require('./frontmatter_schema')
 
-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'
-}
-
-const NAME_PATTERN = /^[a-z][a-z0-9-]*$/
 const PLACEHOLDER_DESC = 'Describe what this skill does and when to invoke it'
 const DESC_SOFT_CAP = 250
 const DESC_TARGET_MIN = 80
 const DESC_TARGET_MAX = 180
 
-const result = (field, rule, severity, message, value) => ({
-	file: SKILL_MD, field, rule, severity, message, ...(value !== undefined ? { value } : {})
+// Every result carries enough structured detail for an LLM (or human) to
+// pinpoint and auto-correct: which file, which field, which YAML line, what
+// the validator expected vs. saw, and — for the common fixable cases — the
+// literal corrected line to write back.
+const result = (field, rule, severity, message, value, extras = {}) => ({
+	file: SKILL_MD,
+	field,
+	rule,
+	severity,
+	message,
+	...(value !== undefined ? { value } : {}),
+	...extras
 })
 
-const validate_name = (fm, dir_name) => {
-	const results = []
-	const name = fm.name
+// Format a parsed YAML type for an error message ("array", "boolean", etc.).
+const fmt_type = (t) => t === 'block_scalar' ? 'block scalar' : t
 
-	if (!name) {
-		results.push(result('name', 'present', 'error', 'Frontmatter must include a "name" field'))
-		return results
+// Schema-driven validation. One pass over every declared field; one pass over
+// every unknown field (with did-you-mean for typos).
+const validate_against_schema = (typed, dir_name) => {
+	const results = []
+	const fields = typed.fields
+
+	// Bubble up structural parse errors (lines without a colon, etc.) first —
+	// they indicate the frontmatter is malformed enough that later checks may
+	// be misleading.
+	for (const err of typed.errors) {
+		results.push(result(null, 'frontmatter_parse', 'error',
+			`SKILL.md line ${err.line}: ${err.message}`,
+			undefined,
+			{ line: err.line }
+		))
 	}
 
-	results.push(result('name', 'present', 'pass', `name: "${name}"`, name))
+	// Required + type + per-rule checks for every known field.
+	for (const key of KNOWN_FIELDS) {
+		const schema = FRONTMATTER_SCHEMA[key]
+		const present = key in fields
+
+		if (!present) {
+			if (schema.required) {
+				results.push(result(key, 'present', 'error',
+					`Frontmatter is missing the required "${key}" field. Add it inside the --- block at the top of SKILL.md.`,
+					undefined,
+					{ fix: `${key}: <value>` }
+				))
+			}
+			continue
+		}
 
-	if (name.length > 64) {
-		results.push(result('name', 'max_length', 'error', `Name is ${name.length} chars (max 64)`, name))
-	} else {
-		results.push(result('name', 'max_length', 'pass', `name: ${name.length} chars (max 64)`, name))
+		const f = fields[key]
+
+		// Type check first — every later rule assumes the type matches.
+		if (!schema.types.includes(f.type)) {
+			const expected = schema.types.join(' or ')
+			const fix_line = f.type === 'array' || f.type === 'object'
+				? `${key}: "${f.raw}"`
+				: null
+			const hint = f.type === 'array'
+				? ` — looks like an unquoted "[...]" was interpreted as a YAML list. Quote the value to keep it as a string. Replace line ${f.line} with: ${fix_line}`
+				: f.type === 'object'
+				? ` — looks like an unquoted "{...}" was interpreted as a YAML map. Quote the value to keep it as a string. Replace line ${f.line} with: ${fix_line}`
+				: ''
+			results.push(result(
+				key,
+				'type',
+				'error',
+				`SKILL.md line ${f.line}: "${key}" must be a ${expected} (got ${fmt_type(f.type)})${hint}`,
+				f.raw,
+				{ line: f.line, expected, actual: fmt_type(f.type), ...(fix_line ? { fix: fix_line } : {}) }
+			))
+			continue
+		}
+
+		results.push(result(key, 'type', 'pass', `${key}: ${fmt_type(f.type)}`, undefined, { line: f.line }))
+
+		// String-specific rules.
+		if (f.type === 'string') {
+			const value = f.value
+
+			if (schema.non_empty && !value.trim()) {
+				results.push(result(key, 'non_empty', 'error',
+					`SKILL.md line ${f.line}: "${key}" must not be empty or whitespace-only`,
+					undefined,
+					{ line: f.line }
+				))
+				continue
+			}
+
+			if (schema.max_length && value.length > schema.max_length) {
+				results.push(result(key, 'max_length', 'error',
+					`SKILL.md line ${f.line}: "${key}" is ${value.length} chars (max ${schema.max_length})`,
+					value,
+					{ line: f.line, length: value.length, max: schema.max_length }
+				))
+			} else if (schema.max_length) {
+				results.push(result(key, 'max_length', 'pass', `${key}: ${value.length} chars (max ${schema.max_length})`, undefined, { line: f.line }))
+			}
+
+			if (schema.pattern && !schema.pattern.test(value)) {
+				results.push(result(key, 'format', 'error',
+					`SKILL.md line ${f.line}: "${key}" ${schema.pattern_message || 'has invalid format'}. Got: "${value}"`,
+					value,
+					{ line: f.line }
+				))
+			}
+
+			if (schema.enum && !schema.enum.includes(value)) {
+				results.push(result(key, 'enum', 'warning',
+					`SKILL.md line ${f.line}: "${key}" should be one of [${schema.enum.join(', ')}], got "${value}"`,
+					value,
+					{ line: f.line, expected: schema.enum, actual: value }
+				))
+			}
+
+			// Forbidden-chars: always run on plain (unquoted) scalars, since those
+			// are the ones that can re-trigger YAML structural parsing in another
+			// loader. For quoted scalars, only run if the schema demands it.
+			const should_scan = schema.forbidden_chars || (schema.forbidden_chars_in_plain_only && f.quoted === 'plain')
+			if (should_scan) {
+				let found = false
+				for (const [char, ch_name] of Object.entries(FORBIDDEN_CHARS)) {
+					const idx = value.indexOf(char)
+					if (idx !== -1) {
+						results.push(result(key, 'no_forbidden_characters', 'error',
+							`SKILL.md line ${f.line}: "${key}" contains forbidden character ${ch_name} ('${char}') at position ${idx} of the value. Rephrase without it.`,
+							value,
+							{ line: f.line, character: char, character_name: ch_name, char_index: idx }
+						))
+						found = true
+						break
+					}
+				}
+				if (!found) results.push(result(key, 'no_forbidden_characters', 'pass', 'No forbidden characters', undefined, { line: f.line }))
+			}
+		}
 	}
 
-	if (!NAME_PATTERN.test(name)) {
-		results.push(result('name', 'format', 'error', 'Name must match /^[a-z][a-z0-9-]*$/', name))
-	} else {
-		results.push(result('name', 'format', 'pass', 'Name format valid', name))
+	// Unknown-field warnings — did-you-mean for likely typos.
+	for (const key of Object.keys(fields)) {
+		if (KNOWN_FIELDS.includes(key)) continue
+		const f = fields[key]
+		const suggestion = did_you_mean(key)
+		if (suggestion) {
+			results.push(result(key, 'unknown_field', 'warning',
+				`SKILL.md line ${f.line}: Unknown frontmatter field "${key}" — did you mean "${suggestion}"? Rename the key on line ${f.line}.`,
+				undefined,
+				{ line: f.line, suggestion, fix: `${suggestion}: ${f.raw}` }
+			))
+		}
 	}
 
+	return results
+}
+
+// Per-field post-checks that go beyond the schema (rich recommendations,
+// name↔dir cross-check, placeholder detection, description soft cap).
+const validate_name_extras = (fields, dir_name) => {
+	const results = []
+	const f = fields.name
+	if (!f || f.type !== 'string') return results
+	const name = f.value
+
 	if (name.includes('--')) {
-		results.push(result('name', 'no_consecutive_hyphens', 'error', 'Name must not contain consecutive hyphens (--)', name))
+		results.push(result('name', 'no_consecutive_hyphens', 'error',
+			`SKILL.md line ${f.line}: Name "${name}" must not contain consecutive hyphens (--)`,
+			name,
+			{ line: f.line }
+		))
 	}
-
 	if (name.startsWith('-') || name.endsWith('-')) {
-		results.push(result('name', 'no_edge_hyphens', 'error', 'Name must not start or end with a hyphen', name))
+		results.push(result('name', 'no_edge_hyphens', 'error',
+			`SKILL.md line ${f.line}: Name "${name}" must not start or end with a hyphen`,
+			name,
+			{ line: f.line }
+		))
 	}
-
 	if (dir_name && name !== dir_name) {
-		results.push(result('name', 'matches_directory', 'warning', `Name "${name}" does not match directory "${dir_name}"`, name))
+		results.push(result('name', 'matches_directory', 'warning',
+			`SKILL.md line ${f.line}: name "${name}" does not match directory "${dir_name}". Rename one so they match.`,
+			name,
+			{ line: f.line, expected: dir_name, actual: name, fix: `name: ${dir_name}` }
+		))
 	} else if (dir_name) {
-		results.push(result('name', 'matches_directory', 'pass', `Name matches directory "${dir_name}"`, name))
+		results.push(result('name', 'matches_directory', 'pass', `Name matches directory "${dir_name}"`, name, { line: f.line }))
 	}
 
 	return results
 }
 
-const validate_description = (fm) => {
+const validate_description_extras = (fields) => {
 	const results = []
-	const desc = fm.description
+	const f = fields.description
+	if (!f || f.type !== 'string') return results
+	const desc = f.value
 
-	if (!desc) {
-		results.push(result('description', 'present', 'error', 'Frontmatter must include a "description" field'))
-		return results
-	}
-
-	results.push(result('description', 'present', 'pass', `description present (${desc.length} chars)`))
-
-	if (!desc.trim()) {
-		results.push(result('description', 'non_empty', 'error', 'Description must not be empty or whitespace-only', desc))
-		return results
+	if (desc === PLACEHOLDER_DESC) {
+		results.push(result('description', 'not_placeholder', 'warning',
+			`SKILL.md line ${f.line}: description is still the init placeholder — update it before publishing`,
+			desc,
+			{ line: f.line }
+		))
 	}
 
 	if (desc.length > 1024) {
-		const deficit = desc.length - 1024
 		results.push({
-			...result('description', 'max_length', 'error', `Description is ${desc.length} chars (max 1024). Must reduce by ${deficit} chars.`, desc),
+			...result('description', 'max_length_advice', 'error',
+				`SKILL.md line ${f.line}: description is ${desc.length} chars (max 1024). Must reduce by ${desc.length - 1024} chars.`,
+				desc,
+				{ line: f.line, length: desc.length, max: 1024 }
+			),
 			recommendations: [
 				'STEP 1 - AUDIT: Before changing anything, read the skill\'s routing table or capability list. Map each phrase in the description to the capability it triggers. Mark each phrase as: IDENTITY (describes what the skill is, usually one phrase), UNIQUE (the only phrase matching a specific capability), or REINFORCING (overlaps with another phrase\'s coverage).',
 				'STEP 2 - LOSSLESS COMPRESSION: Apply these transformations that reduce characters without changing semantic meaning: (a) Remove articles (a, an, the). (b) Remove possessives (my, your) when the subject is implied. (c) Remove filler verbs (do, does, can, have, is, am). (d) Merge parallel structures that share the same verb (e.g., \'install kit. publish kit\' becomes \'install, publish kits\') or the same object (e.g., \'find kits, search kits\' becomes \'find, search kits\'). Stop here if now under the limit.',
@@ -90,79 +237,75 @@ const validate_description = (fm) => {
 				'STEP 4 - VERIFY: Cross-check the shortened description against the skill\'s routing table or capability list. Every documented capability must still have at least one semantically matching phrase in the description. If any capability lost coverage, restore its trigger phrase and find different savings.'
 			]
 		})
+	} else if (desc.length <= DESC_SOFT_CAP) {
+		results.push(result('description', 'soft_cap', 'pass', `Description: ${desc.length} chars (soft cap ${DESC_SOFT_CAP})`, undefined, { line: f.line }))
 	} else {
-		results.push(result('description', 'max_length', 'pass', `Description: ${desc.length} chars (max 1024)`))
-
-		if (desc.length > DESC_SOFT_CAP) {
-			results.push({
-				...result('description', 'soft_cap', 'warning', `Description is ${desc.length} chars (target: ${DESC_TARGET_MIN}-${DESC_TARGET_MAX}, soft cap: ${DESC_SOFT_CAP}). Above ${DESC_SOFT_CAP} chars usually signals a mega-skill — apply the Constellation Pattern to decompose it into a core skill plus focused satellites. Run "npx happyskills audit <name>" or ask your agent "audit this skill" — happyskills-design will walk you through the Constellation Decomposition Workflow.`, desc),
-				recommendations: [
-					'CANONICAL — Apply the Constellation Pattern: decompose the skill into a core entry-point skill plus satellite skills, each owning one orthogonal verb cluster, bundled via the core skill.json dependencies. This is the answer once a description crosses the soft cap. happyskills-design implements the Constellation Decomposition Workflow end-to-end — invoke it with "audit this skill" or "decompose this mega-skill".',
-					'Alternative — Compress the description first (AUDIT/LOSSLESS/LOSSY procedure in happyskills-design references/skill-authoring.md). Buys time, but compression alone will not keep up as the API surface grows.',
-					'Alternative — Hybrid umbrella+satellites: keep one main skill for high-frequency operations, extract specialized domains into satellites.',
-					'For the canonical Constellation Pattern reference (orthogonal verb ownership, the five-slot description grammar, failure modes, orthogonality test): happyskills-design references/constellation-pattern.md, or docs/cli-skill.md in the HappySkills repo.'
-				]
-			})
-		} else {
-			results.push(result('description', 'soft_cap', 'pass', `Description: ${desc.length} chars (soft cap ${DESC_SOFT_CAP})`))
-		}
+		results.push({
+			...result('description', 'soft_cap', 'warning', `SKILL.md line ${f.line}: description is ${desc.length} chars (target: ${DESC_TARGET_MIN}-${DESC_TARGET_MAX}, soft cap: ${DESC_SOFT_CAP}). Above ${DESC_SOFT_CAP} chars usually signals a mega-skill — apply the Constellation Pattern to decompose it into a core skill plus focused satellites. Run "npx happyskills audit <name>" or ask your agent "audit this skill" — happyskills-design will walk you through the Constellation Decomposition Workflow.`, desc),
+			recommendations: [
+				'CANONICAL — Apply the Constellation Pattern: decompose the skill into a core entry-point skill plus satellite skills, each owning one orthogonal verb cluster, bundled via the core skill.json dependencies. This is the answer once a description crosses the soft cap. happyskills-design implements the Constellation Decomposition Workflow end-to-end — invoke it with "audit this skill" or "decompose this mega-skill".',
+				'Alternative — Compress the description first (AUDIT/LOSSLESS/LOSSY procedure in happyskills-design references/skill-authoring.md). Buys time, but compression alone will not keep up as the API surface grows.',
+				'Alternative — Hybrid umbrella+satellites: keep one main skill for high-frequency operations, extract specialized domains into satellites.',
+				'For the canonical Constellation Pattern reference (orthogonal verb ownership, the five-slot description grammar, failure modes, orthogonality test): happyskills-design references/constellation-pattern.md, or docs/cli-skill.md in the HappySkills repo.'
+			]
+		})
 	}
 
-	if (desc === PLACEHOLDER_DESC) {
-		results.push(result('description', 'not_placeholder', 'warning', 'Description is the init placeholder — update it before publishing', desc))
-	}
+	return results
+}
 
-	for (const [char, name] of Object.entries(FORBIDDEN_CHARS)) {
-		if (desc.includes(char)) {
-			results.push(result('description', 'no_forbidden_characters', 'error', `Description contains forbidden character: ${name} (${char})`, desc))
-			return results
-		}
+const validate_agent_requires_fork = (fields) => {
+	const results = []
+	if (fields.agent === undefined) return results
+	const context = fields.context
+	const agent_f = fields.agent
+	if (!context || context.value !== 'fork') {
+		results.push(result('agent', 'requires_context', 'warning',
+			`SKILL.md line ${agent_f.line}: agent is set but context is not "fork" — agent skills require "context: fork". Add (or change) the context line.`,
+			undefined,
+			{ line: agent_f.line, fix: 'context: fork' }
+		))
 	}
-
-	results.push(result('description', 'no_forbidden_characters', 'pass', 'No forbidden characters'))
 	return results
 }
 
-const validate_optional_fields = (fm) => {
-	const results = []
+const validate_skill_md = (skill_dir, dir_name, skill_type) => catch_errors('Failed to validate SKILL.md', async () => {
+	const is_kit = skill_type === SKILL_TYPES.KIT
 
-	if (fm.compatibility !== undefined) {
-		if (fm.compatibility.length > 500) {
-			results.push(result('compatibility', 'max_length', 'error', `Compatibility is ${fm.compatibility.length} chars (max 500)`, fm.compatibility))
-		} else {
-			results.push(result('compatibility', 'max_length', 'pass', `Compatibility: ${fm.compatibility.length} chars (max 500)`))
+	// Kits have no SKILL.md at all — they ship a README.md describing the
+	// bundle. Validate that branch separately so the file-label, error
+	// messages, and skipped checks all reflect the kit format.
+	if (is_kit) {
+		const readme_path = path.join(skill_dir, README_MD)
+		const skill_md_path = path.join(skill_dir, SKILL_MD)
+		const kit_result = (field, rule, severity, message, value) => ({
+			file: README_MD, field, rule, severity, message, ...(value !== undefined ? { value } : {})
+		})
+		const kit_results = []
+		const [, readme_exists] = await file_exists(readme_path)
+		if (!readme_exists) {
+			kit_results.push(kit_result(null, 'exists', 'error', 'README.md not found (required for kits)'))
+			return { results: kit_results, frontmatter: null, content: null }
 		}
-	}
-
-	const bool_fields = ['disable-model-invocation', 'user-invocable']
-	for (const field of bool_fields) {
-		if (fm[field] !== undefined) {
-			const val = fm[field]
-			if (val !== 'true' && val !== 'false') {
-				results.push(result(field, 'boolean_type', 'warning', `${field} should be true or false, got "${val}"`, val))
-			} else {
-				results.push(result(field, 'boolean_type', 'pass', `${field}: ${val}`))
-			}
+		kit_results.push(kit_result(null, 'exists', 'pass', 'README.md exists'))
+
+		// Kits must NOT contain a SKILL.md — its presence would re-expose
+		// the kit to agent auto-invocation and re-trigger the frontmatter
+		// warnings in Codex/Gemini that the README.md format exists to avoid.
+		const [, skill_md_exists] = await file_exists(skill_md_path)
+		if (skill_md_exists) {
+			kit_results.push({
+				file: SKILL_MD, field: null, rule: 'not_in_kit', severity: 'error',
+				message: 'Kits must not contain a SKILL.md — delete it. Kit documentation belongs in README.md.'
+			})
 		}
-	}
-
-	if (fm.context !== undefined && fm.context !== 'fork') {
-		results.push(result('context', 'value', 'warning', `context should be "fork", got "${fm.context}"`, fm.context))
-	} else if (fm.context !== undefined) {
-		results.push(result('context', 'value', 'pass', 'context: fork'))
-	}
 
-	if (fm.agent !== undefined && fm.context !== 'fork') {
-		results.push(result('agent', 'requires_context', 'warning', 'agent is set but context is not "fork" — agent skills require context: fork'))
+		const [, readme_content] = await read_file(readme_path)
+		return { results: kit_results, frontmatter: null, content: readme_content }
 	}
 
-	return results
-}
-
-const validate_skill_md = (skill_dir, dir_name, skill_type) => catch_errors('Failed to validate SKILL.md', async () => {
 	const results = []
 	const md_path = path.join(skill_dir, SKILL_MD)
-	const is_kit = skill_type === SKILL_TYPES.KIT
 
 	const [, exists] = await file_exists(md_path)
 	if (!exists) {
@@ -174,22 +317,23 @@ const validate_skill_md = (skill_dir, dir_name, skill_type) => catch_errors('Fai
 
 	const [, content] = await read_file(md_path)
 
-	if (is_kit) {
-		return { results, frontmatter: null, content }
-	}
-
+	// Two parses: the legacy plain-string parser keeps downstream callers
+	// (cross-rule validation, convert, etc.) working unchanged, while the
+	// typed parser is what the schema runs against.
 	const fm = parse_frontmatter(content)
+	const typed = parse_typed(content)
 
-	if (!fm) {
+	if (!typed) {
 		results.push(result(null, 'frontmatter', 'error', 'SKILL.md has no YAML frontmatter (---)'))
 		return { results, frontmatter: null, content }
 	}
 
 	results.push(result(null, 'frontmatter', 'pass', 'Frontmatter present'))
 
-	results.push(...validate_name(fm, dir_name))
-	results.push(...validate_description(fm))
-	results.push(...validate_optional_fields(fm))
+	results.push(...validate_against_schema(typed, dir_name))
+	results.push(...validate_name_extras(typed.fields, dir_name))
+	results.push(...validate_description_extras(typed.fields))
+	results.push(...validate_agent_requires_fork(typed.fields))
 
 	const line_count = content.split('\n').length
 	if (line_count >= 500) {