What
Once validate starts erroring on non-spec frontmatter (top-level scalar keys, a slash/non-leaf name, a non-string metadata map), every existing skill needs to be migrated to the new shape. Doing that by hand across a package's skill tree is tedious and error-prone. validate should be able to perform the mechanical migration itself via a --fix flag.
What --fix does
The mechanical, unambiguous rewrites only:
- Rewrite
name to the spec-legal leaf matching the parent directory.
- Move the scalar fields (
type, library, library_version, framework) under metadata.
It must not touch anything requiring authoring judgment (missing/short description, length-limit failures, etc.) — those stay as plain validation errors.
Where this comes from
- This is the migration path for the spec-compliance changes (see the spec-compliant
name/metadata issue). Without it, the breaking frontmatter change has no automated upgrade and every maintainer hand-edits.
- The maintainer in discussion Generated skill frontmatter compliance. #116 offered to do the compliance work; a
--fix flow is what makes that compliance change adoptable rather than a manual chore.
Implementation note / risk
The repo already depends on yaml (eemeli/yaml), whose Document API (parseDocument → setIn/deleteIn → toString) preserves comments, blank lines, and key order — so --fix can rewrite only the frontmatter block without reformatting the whole file. The current validate path uses the plain parse() (value-only), which would destroy comments/formatting on write, so --fix needs the Document API specifically.
yaml's own docs note that trailing-comment handling "is not completely stable", so the rewrite needs round-trip tests (including a fixture with trailing comments on the migrated keys), idempotency, and a --check/dry-run mode that reports pending fixes without writing (for CI).
What
Once
validatestarts erroring on non-spec frontmatter (top-level scalar keys, a slash/non-leafname, a non-stringmetadatamap), every existing skill needs to be migrated to the new shape. Doing that by hand across a package's skill tree is tedious and error-prone.validateshould be able to perform the mechanical migration itself via a--fixflag.What --fix does
The mechanical, unambiguous rewrites only:
nameto the spec-legal leaf matching the parent directory.type,library,library_version,framework) undermetadata.It must not touch anything requiring authoring judgment (missing/short
description, length-limit failures, etc.) — those stay as plain validation errors.Where this comes from
name/metadata issue). Without it, the breaking frontmatter change has no automated upgrade and every maintainer hand-edits.--fixflow is what makes that compliance change adoptable rather than a manual chore.Implementation note / risk
The repo already depends on
yaml(eemeli/yaml), whose Document API (parseDocument→setIn/deleteIn→toString) preserves comments, blank lines, and key order — so--fixcan rewrite only the frontmatter block without reformatting the whole file. The currentvalidatepath uses the plainparse()(value-only), which would destroy comments/formatting on write, so--fixneeds the Document API specifically.yaml's own docs note that trailing-comment handling "is not completely stable", so the rewrite needs round-trip tests (including a fixture with trailing comments on the migrated keys), idempotency, and a--check/dry-run mode that reports pending fixes without writing (for CI).