feat: validate skill reference files

[LadyBluenotes]

🎯 Changes

Intent's authoring guidance tells maintainers to move detail into references/*.md beside a SKILL.md, but intent validate looked only at SKILL.md files. Reference files had no checks. TanStack Table moved 66 files into references and wrote its own script to check them.

intent validate now checks every Markdown file under a skill's references/ directory.

For every skill that has reference files:

• No frontmatter. A reference is plain Markdown. Frontmatter would make it look like a skill.
• Direct link from SKILL.md. intent load returns only SKILL.md, so an agent finds a reference through that link. A reference may also link to another reference; that is never an error, and it does not replace the link from SKILL.md.
• Examples typecheck. TypeScript and JavaScript fences in references join the same program as the skill's own examples.

When the skill has an entry in skill_tree.yaml:

• The entry must list the reference files in a references key. When the key is missing, the error prints the lines to add.
• The list must match the files: each path is references/<name>.md inside the skill directory, appears once, exists on disk, and every reference file on disk is listed.

skills:
  - name: Table State
    slug: table-state
    package: packages/react-table
    path: skills/table-state/SKILL.md
    references:
      - references/reactivity.md

A skill with no reference files needs nothing. A repository with no planning artifacts gets the file checks only.

Upgrade impact

An existing repository now fails validate when a reference file has frontmatter, has no direct link from SKILL.md, contains an example that does not typecheck, or is missing from its skill's tree entry. One of Intent's own meta skills needed a link added for the direct-link rule.

[changeset-bot]

🦋 Changeset detected

Latest commit: e937ff6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@tanstack/intent	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 5 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: a2a64b8e-ffa3-4bf9-843c-a1f9a75931d2

📥 Commits

Reviewing files that changed from the base of the PR and between 894ab61 and e937ff6.

📒 Files selected for processing (10)

• .changeset/validate-skill-references.md
• docs/cli/intent-validate.md
• packages/intent/meta/generate-skill/SKILL.md
• packages/intent/meta/generate-skill/references/planning-records.md
• packages/intent/meta/generate-skill/references/skill-format.md
• packages/intent/src/commands/validate.ts
• packages/intent/src/shared/types.ts
• packages/intent/src/staleness/artifact-coverage.ts
• packages/intent/src/validate/blocks.ts
• packages/intent/tests/cli.test.ts

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 6a4e32b

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:sherif,t...	✅ Succeeded	1m 2s	View ↗
nx run-many --targets=build	✅ Succeeded	2s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-10-04 18:10:25 UTC

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@tanstack/intent@318

commit: e937ff6

[codspeed]

Merging this PR will degrade performance by 14.06%

❌ 1 regressed benchmark
✅ 11 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	checks a shipped skills tree	148.5 ms	172.8 ms	-14.06%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing feat/validate-skill-references (e937ff6) with main (894ab61)}