Spec-compliant SKILL.md frontmatter

[LadyBluenotes]

Closes #160

Makes generated SKILL.md frontmatter compliant with the Agent Skills specification.

Changes

• name must be a spec-legal leaf segment matching its parent directory: lowercase letters, numbers, and hyphens only, 64 characters max, no slashes.
• type, library, library_version, and framework move under the metadata map instead of being top-level keys.
• intent validate now errors on: a slash/non-leaf name, a name with non-spec characters, a name over 64 characters, non-spec top-level scalar keys, and a non-string metadata map.
• Skill identity is derived from the directory path rather than the frontmatter name.
• The generate-skill and tree-generator templates emit the new shape, with placeholder values quoted so the example metadata parses as strings.
• Removes the unused scripts/validate-skills.ts validator (superseded by intent validate) and the now-orphaned root yaml dependency.
• sources and requires remain top-level for now (separate follow-up).

Summary by CodeRabbit

Release Notes

• Documentation

  • Updated skill definition validation rules and frontmatter templates to reflect new requirements

• Breaking Changes

  • Skill names must be single leaf segments using only lowercase letters, numbers, and hyphens
  • Intent-specific fields (type, library, library_version, framework) moved under a metadata map
  • Skill identity now derived from directory structure

• Tests

  • Enhanced validation test coverage for naming conventions and metadata structure

• Chores

  • Removed standalone validation utility script

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR enforces a spec-compliant SKILL.md frontmatter schema: name must be a single lowercase leaf segment matching the parent directory, and intent-specific scalars (type, library, library_version, framework) move under a metadata map. Skill identity is now derived from filesystem path rather than frontmatter across the scanner, staleness checker, and validator. The legacy scripts/validate-skills.ts is removed.

Changes

SKILL.md Frontmatter Schema Overhaul

Layer / File(s)	Summary
New frontmatter schema contract and validator helpers packages/intent/src/commands/validate.ts, packages/intent/src/staleness.ts	Defines specTopLevelKeys, intentArrayKeys, and isScalarValue type guard in the validator; updates SkillMeta to key by relName instead of frontmatter name; removes sep from path imports.
Scanner derives skill identity from filesystem path packages/intent/src/scanner.ts, packages/intent/tests/scanner.test.ts	readSkillEntry always assigns name from relName, ignoring fm.name. Scanner tests confirm a frontmatter name mismatch no longer returns an empty result.
Staleness checker uses relName as skill identity packages/intent/src/staleness.ts	findMatchingSkill indexes by relName; checkStaleness no longer reads fm.name; artifact drift signals and per-skill reports emit relName.
Validator: leaf-name enforcement and non-spec key rejection packages/intent/src/commands/validate.ts	Replaces old path comparison with leaf-segment validation (length, no slashes, parent-dir match, lowercase-alphanumeric-hyphen regex). Adds loop rejecting non-spec top-level scalar keys. Extends metadata type/value checks. Refactors collectAgentSkillSpecWarnings signature to { fm, rel }.
Remove legacy validate-skills.ts script and yaml devDependency scripts/validate-skills.ts, package.json	Deletes the 202-line standalone validate-skills.ts script whose functionality is now covered by the intent CLI; removes the yaml root devDependency.
Generator templates updated to new schema packages/intent/meta/generate-skill/SKILL.md, packages/intent/meta/tree-generator/SKILL.md	All SKILL.md template examples move type, library, library_version, framework under metadata and use leaf-only name values across core, sub-skill, framework, composition, and security skill types.
Tests and documentation packages/intent/tests/cli.test.ts, docs/cli/intent-validate.md, docs/getting-started/quick-start-maintainers.md, .changeset/frank-experts-build.md	CLI tests add failure cases for slash names, non-spec scalars, invalid metadata shapes, and fix uppercase-name expectation to exit code 1. Docs document new name and metadata constraints. Changeset recorded.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• TanStack/intent#162: Adds readScalarField to read type/framework/library_version from metadata.* with a top-level fallback, directly touching the same scanner.ts, staleness.ts, and validate.ts paths modified by this PR.

Suggested reviewers

• KevinVandy
• schiller-manuel

Poem

🐇 Hop, hop, the frontmatter grew neat,
No slashes in names — a leaf-only feat!
type tucked in metadata, tidy and small,
The path tells the story, the best name of all.
One rabbit, one rule, one clean spec to meet! 🌿

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description provides detailed changes and motivation. However, it does not follow the required template structure with the 🎯 Changes, ✅ Checklist, and 🚀 Release Impact sections as specified in the template.	Reorganize the description to match the template: add the three required sections (Changes, Checklist, Release Impact) with checkboxes and links as shown in the template.
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.22% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Spec-compliant SKILL.md frontmatter' directly and clearly summarizes the main change: making generated SKILL.md frontmatter comply with the Agent Skills specification.
Linked Issues check	✅ Passed	All requirements from issue #160 are addressed: name field restricted to leaf segments with spec-legal characters and 64-char limit [#160], metadata reorganization moving type/library/library_version/framework under metadata [#160], enhanced validation in intent validate command [#160], template updates for new shape [#160], and code cleanup removing validate-skills.ts and yaml dependency [#160].
Out of Scope Changes check	✅ Passed	All changes are directly related to the PR objective of making SKILL.md frontmatter spec-compliant: validation rules, template updates, documentation, test updates, and dependency cleanup are all in-scope changes aligned with issue #160.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/spec-compliant-skill-metadata

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

packages/intent/src/staleness.ts (1)

530-548: 💤 Low value

Migration note: existing sync-state.json files may need regeneration.

The lookup key changed from frontmatter name to path-derived relName. Existing projects with sync-state.json keyed by old multi-segment names (e.g., routing/file-based) will not match the new leaf-segment keys (e.g., file-based), potentially causing false staleness signals until the sync-state is regenerated.

This appears intentional for spec compliance, but consider documenting this migration step in the changeset or docs.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/intent/src/staleness.ts` around lines 530 - 548, The lookup key for
stored source SHAs has changed from the old frontmatter name field (which
supported multi-segment paths like routing/file-based) to the new relName field
(which uses only the leaf segment like file-based). Existing sync-state.json
files keyed with the old multi-segment names will not match the new relName
keys, potentially causing false staleness signals. Document this breaking change
in the changeset and add migration guidance in the documentation explaining that
existing projects with sync-state.json files may need to regenerate them to work
with the new relName-based lookup key used in this staleness checking logic.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@packages/intent/src/staleness.ts`:
- Around line 530-548: The lookup key for stored source SHAs has changed from
the old frontmatter name field (which supported multi-segment paths like
routing/file-based) to the new relName field (which uses only the leaf segment
like file-based). Existing sync-state.json files keyed with the old
multi-segment names will not match the new relName keys, potentially causing
false staleness signals. Document this breaking change in the changeset and add
migration guidance in the documentation explaining that existing projects with
sync-state.json files may need to regenerate them to work with the new
relName-based lookup key used in this staleness checking logic.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b2d7ba2d-e318-4641-9f4f-00ab6048e1f6

📥 Commits

Reviewing files that changed from the base of the PR and between 9db6592 and f8639c0.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (12)

• .changeset/frank-experts-build.md
• docs/cli/intent-validate.md
• docs/getting-started/quick-start-maintainers.md
• package.json
• packages/intent/meta/generate-skill/SKILL.md
• packages/intent/meta/tree-generator/SKILL.md
• packages/intent/src/commands/validate.ts
• packages/intent/src/scanner.ts
• packages/intent/src/staleness.ts
• packages/intent/tests/cli.test.ts
• packages/intent/tests/scanner.test.ts
• scripts/validate-skills.ts

💤 Files with no reviewable changes (1)

• scripts/validate-skills.ts

[nx-cloud]

View your CI Pipeline Execution ↗ for commit f8639c0

---

☁️ Nx Cloud last updated this comment at 2026-06-19 19:59:07 UTC