Agent skill: most cross-file links under references/ do not resolve

[keitakn]

🙋 Documentation Request

Most of the cross-file links under references/ in the published React Aria agent skill do not resolve.

What I see

I downloaded all 167 files listed in https://react-aria.adobe.com/.well-known/skills/index.json and resolved every relative Markdown link in the 166 .md files against the directory each file sits in. 102 of 267 links do not resolve. 88 of those point at a file that does exist elsewhere in the skill.

• ](forms.md) in references/components/Checkbox.md — the file is at references/guides/forms.md
• ](usePress.md) in references/components/Button.md — the file is at references/interactions/usePress.md

Six of the remaining 14 are ](internationalized/date/.md), with the filename missing. They appear in Calendar.md, DateField.md, DatePicker.md, DateRangePicker.md, RangeCalendar.md and TimeField.md under references/components/. The rest point at blog posts, which I assume are simply not shipped with the skill.

All 71 links in SKILL.md itself resolve. Only the ones inside references/ are off.

Steps to reproduce

curl -s https://react-aria.adobe.com/.well-known/skills/react-aria/references/components/Checkbox.md | grep -o '\](forms[^)]*)'
# ](forms.md)

curl -s -o /dev/null -w '%{http_code}\n' https://react-aria.adobe.com/.well-known/skills/react-aria/references/components/forms.md
# 404

curl -s -o /dev/null -w '%{http_code}\n' https://react-aria.adobe.com/.well-known/skills/react-aria/references/guides/forms.md
# 200

Where I think this comes from

In packages/dev/s2-docs/pages/react-aria/Checkbox.mdx the link is written as ](forms). Site routes are flat, so that reaches /forms. The Markdown docs build appears to append .md to it.

generateAgentSkills.mjs then copies those Markdown files into references/components/, references/guides/ and the rest with fs.copyFileSync. I could not find a step that rewrites links. A link written for a flat layout ends up in a nested one, so it misses.

The same area may be why CI does not catch it. validateSkillLinks() only reads SKILL.md, and its pattern /\[([^\]]*)\]\((references\/[^)]+)\)/g only matches links that start with references/. A bare ](forms.md) slips through even in SKILL.md.

This part is my reading of the code. I have not run the build to confirm it.

Impact

The content of each file is fine. What breaks is navigation: an agent following the link from the Checkbox doc to the Forms guide lands nowhere. It can recover by searching for the filename, so this is not a dead end.

What I would like

Rewrite the links under references/ to match the layout the skill ships in. Widening validateSkillLinks() to cover files under references/ would also catch this next time.

Notes

Checked against the skill served on 2026-08-17. I searched open and closed issues first: #10007 and #10221 are about skill discovery (/.well-known/agent-skills/index.json), which is a different problem.