What
As part of bringing SKILL.md frontmatter into Agent Skills spec compliance, several Intent-specific fields are moving from the top level of the frontmatter into the spec's metadata map (type, library, library_version, framework). Once that move happens, any skill published with the old top-level shape will stop being read correctly unless the readers understand both shapes.
Where this comes from
Today these fields are read from the top level in two places:
scanner.ts (readSkillEntry) reads type and framework and puts them on the SkillEntry that flows to consumers.
staleness.ts (checkStaleness) reads library_version to compare a skill's targeted version against the installed package version.
When the generator starts emitting these fields under metadata instead, existing published skills (which still carry the top-level shape) would read as missing type/framework/library_version — silently degrading discovery and staleness detection during the migration window.
This only concerns the scalar fields that move into metadata. The array fields (sources, requires) move to a different structured surface, not metadata, and are tracked separately.
What
As part of bringing
SKILL.mdfrontmatter into Agent Skills spec compliance, several Intent-specific fields are moving from the top level of the frontmatter into the spec'smetadatamap (type,library,library_version,framework). Once that move happens, any skill published with the old top-level shape will stop being read correctly unless the readers understand both shapes.Where this comes from
Today these fields are read from the top level in two places:
scanner.ts(readSkillEntry) readstypeandframeworkand puts them on theSkillEntrythat flows to consumers.staleness.ts(checkStaleness) readslibrary_versionto compare a skill's targeted version against the installed package version.When the generator starts emitting these fields under
metadatainstead, existing published skills (which still carry the top-level shape) would read as missingtype/framework/library_version— silently degrading discovery and staleness detection during the migration window.This only concerns the scalar fields that move into
metadata. The array fields (sources,requires) move to a different structured surface, notmetadata, and are tracked separately.