chore: add Agent Skills #9515

reidbarber · 2026-01-23T23:46:09Z

Related to #9508.

Adds a script to generate Agent Skills based on our documentation.

This yarn generate:skills script uses our existing markdown docs build output, and copies/formats them to match the Agent Skills spec. The script outputs these into our docs build in the .well-known/ directory.

Users will be able to install them by via npx skills:

npx skills add https://react-spectrum.adobe.com
npx skills add https://react-aria.adobe.com

More resources:

Overview: https://agentskills.io/home
Cursor integration: https://cursor.com/docs/context/skills
Claude integration: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
VSCode integration: https://code.visualstudio.com/docs/copilot/customization/agent-skills
Vercel's Skill Directory: https://skills.sh/
Discovery RFC: https://github.com/cloudflare/agent-skills-discovery-rfc
Why do we need MCP if skills exist now?: https://www.mintlify.com/blog/why-do-we-need-mcp-if-skills-exist

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

Try running these in any project:

React Spectrum (S2):

npx skills add https://d1pzu54gtk2aed.cloudfront.net/pr/94a22af3fcd09be55c2614e05cdfb7730361d00f/

React Aria:

npx skills add https://d5iwopk28bdhl.cloudfront.net/pr/94a22af3fcd09be55c2614e05cdfb7730361d00f/

The skills should get placed in the current project.

Check the new /ai docs pages:

React Aria: https://d5iwopk28bdhl.cloudfront.net/pr/94a22af3fcd09be55c2614e05cdfb7730361d00f/ai
React Spectrum: https://d1pzu54gtk2aed.cloudfront.net/pr/94a22af3fcd09be55c2614e05cdfb7730361d00f/ai

Verify the old /mcp links now redirect to the /ai mcp section:

React Aria: https://d5iwopk28bdhl.cloudfront.net/pr/94a22af3fcd09be55c2614e05cdfb7730361d00f/mcp
React Spectrum: https://d1pzu54gtk2aed.cloudfront.net/pr/94a22af3fcd09be55c2614e05cdfb7730361d00f/mcp

and verify the old mcp pages aren't visible in search or in the sidebar.

🧢 Your Project:

devongovett · 2026-01-26T19:58:41Z

do we need to commit these or can we deploy them as part of the docs build?

reidbarber · 2026-01-26T20:13:07Z

@devongovett I think the other options are:

Publish a custom CLI tool (run via npx) that pulls from docs CDN and places skills in the user's current directory
Include a setup.sh script in the rules directory that that pulls from docs CDN

I guess the setup.sh solution requires the least maintenance, but requires some extra work on the user's end.

reidbarber · 2026-01-29T23:50:25Z

Discussed with the team, and it seems like we're leaning towards this solution:

We release an Artifact with the zipped markdown docs each release.
Have our skills include a script that downloads and unzips that (optionally, use the user's installed version?)

reidbarber · 2026-01-30T00:09:27Z

Just noticed that npx skills added support for well-known vercel-labs/skills#138

so we might be able to just deploy these to the CDN and have them be installed that way.

This reverts commit 62b2283.

rspbot · 2026-01-30T02:52:27Z

Build successful! 🎉

rspbot · 2026-01-30T02:55:01Z

Build successful! 🎉

rspbot · 2026-01-30T03:57:52Z

Build successful! 🎉

packages/dev/s2-docs/scripts/generateAgentSkills.mjs

rspbot · 2026-02-02T19:24:50Z

Build successful! 🎉

packages/dev/s2-docs/pages/s2/mcp.mdx

packages/dev/s2-docs/pages/s2/ai.mdx

packages/dev/s2-docs/pages/react-aria/mcp.mdx

rspbot · 2026-02-02T19:43:10Z

Build successful! 🎉

snowystinger · 2026-02-02T19:47:49Z

package.json

    "build:s2-docs": "yarn workspace @react-spectrum/s2-docs build",
    "check:s2-docs-build": "node packages/dev/s2-docs/scripts/validateS2DocsBuild.mjs",
    "build:mcp": "yarn workspace @react-spectrum/mcp build && yarn workspace @react-aria/mcp build",
+    "generate:skills": "node packages/dev/s2-docs/scripts/generateAgentSkills.mjs",


make a script target in s2

Suggested change

"generate:skills": "node packages/dev/s2-docs/scripts/generateAgentSkills.mjs",

"generate:skills": "yarn workspace @react-spectrum/s2 generate:skills",

snowystinger · 2026-02-02T19:48:15Z

packages/dev/s2-docs/package.json

    "start:s2": "DOCS_ENV=dev LIBRARY=s2 parcel 'pages/s2/**/*.mdx' -p 4321 --config .parcelrc-s2-docs --dist-dir dist/s2 --cache-dir ../../../.parcel-cache/s2",
    "start:react-aria": "DOCS_ENV=dev LIBRARY=react-aria parcel 'pages/react-aria/**/*.mdx' -p 1234 --config .parcelrc-s2-docs --dist-dir dist/react-aria --cache-dir ../../../.parcel-cache/react-aria",
-    "build": "yarn build:s2 --public-url $PUBLIC_URL && yarn build:react-aria --public-url $PUBLIC_URL",
+    "build": "yarn build:s2 --public-url $PUBLIC_URL && yarn build:react-aria --public-url $PUBLIC_URL && node scripts/generateAgentSkills.mjs",


if you make a target this can change to

Suggested change

"build": "yarn build:s2 --public-url $PUBLIC_URL && yarn build:react-aria --public-url $PUBLIC_URL && node scripts/generateAgentSkills.mjs",

"build": "yarn build:s2 --public-url $PUBLIC_URL && yarn build:react-aria --public-url $PUBLIC_URL && yarn generate:skills",

snowystinger · 2026-02-02T19:49:23Z

Makefile

 	mkdir -p dist/s2-docs/react-aria/$(PUBLIC_URL)
 	mkdir -p dist/s2-docs/s2/$(PUBLIC_URL)
 	mv packages/dev/s2-docs/dist/react-aria/* dist/s2-docs/react-aria/$(PUBLIC_URL)
+	if [ -d packages/dev/s2-docs/dist/react-aria/.well-known ]; then mv packages/dev/s2-docs/dist/react-aria/.well-known dist/s2-docs/react-aria/$(PUBLIC_URL); fi


why the if check?

reidbarber added 2 commits January 23, 2026 17:23

add script to generate agent skills

2702cff

init agent skills

9ba3954

reidbarber mentioned this pull request Jan 27, 2026

docs(S2): Improve markdown output for Style Macro reference page #9535

Merged

5 tasks

reidbarber added 6 commits January 29, 2026 19:51

remove generated rules

62b2283

output to .well-known

d1f1462

clean up script

c3f56e8

Merge remote-tracking branch 'origin/main' into agent-skills

37a23f9

Revert "remove generated rules"

f802620

This reverts commit 62b2283.

remove generated skills from repo

68b03d0

explicitly move .well-known in build-s2-docs

9f6cb62

devongovett previously approved these changes Jan 31, 2026

View reviewed changes

packages/dev/s2-docs/scripts/generateAgentSkills.mjs Outdated Show resolved Hide resolved

remove truncation from lists in SKILLS.md

9aecdc0

reidbarber added the release label Feb 2, 2026

reidbarber added 2 commits February 2, 2026 13:15

add docs (consolidate with mcp docs)

7bb658f

Merge remote-tracking branch 'origin/main' into agent-skills

94a22af

reidbarber dismissed devongovett’s stale review via 94a22af February 2, 2026 19:16

devongovett reviewed Feb 2, 2026

View reviewed changes

packages/dev/s2-docs/pages/s2/mcp.mdx Outdated Show resolved Hide resolved

devongovett reviewed Feb 2, 2026

View reviewed changes

packages/dev/s2-docs/pages/s2/ai.mdx Outdated Show resolved Hide resolved

snowystinger reviewed Feb 2, 2026

View reviewed changes

packages/dev/s2-docs/pages/react-aria/mcp.mdx Show resolved Hide resolved

review comments

a9b7ee5

devongovett approved these changes Feb 2, 2026

View reviewed changes

reidbarber enabled auto-merge February 2, 2026 19:53

snowystinger approved these changes Feb 2, 2026

View reviewed changes

reidbarber added this pull request to the merge queue Feb 2, 2026

Merged via the queue into main with commit 5fee021 Feb 2, 2026
27 of 29 checks passed

reidbarber deleted the agent-skills branch February 2, 2026 20:47

	"generate:skills": "node packages/dev/s2-docs/scripts/generateAgentSkills.mjs",
	"generate:skills": "yarn workspace @react-spectrum/s2 generate:skills",

	"build": "yarn build:s2 --public-url $PUBLIC_URL && yarn build:react-aria --public-url $PUBLIC_URL && node scripts/generateAgentSkills.mjs",
	"build": "yarn build:s2 --public-url $PUBLIC_URL && yarn build:react-aria --public-url $PUBLIC_URL && yarn generate:skills",

chore: add Agent Skills #9515

chore: add Agent Skills #9515

Uh oh!

Conversation

reidbarber commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

devongovett commented Jan 26, 2026

Uh oh!

reidbarber commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

reidbarber commented Jan 29, 2026

Uh oh!

reidbarber commented Jan 30, 2026

Uh oh!

rspbot commented Jan 30, 2026

Uh oh!

rspbot commented Jan 30, 2026

Uh oh!

rspbot commented Jan 30, 2026

Uh oh!

Uh oh!

rspbot commented Feb 2, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rspbot commented Feb 2, 2026

Uh oh!

snowystinger Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

snowystinger Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

snowystinger Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

reidbarber commented Jan 23, 2026 •

edited

Loading

reidbarber commented Jan 26, 2026 •

edited

Loading