docs(repo): Expand AGENTS.md with toolchain, changeset, and commit rules

[jacekradko]

Low hanging fruit additions to the AGENTS file that should speed up monorepo discovery

Also linked to the docs/CONTRIBUTING.md for additional monorepo context

[changeset-bot]

🦋 Changeset detected

Latest commit: 9ecc102

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

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 21, 2026 12:36pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 0ab9bab4-b794-4b5e-bb5b-1d42c60e25c7

📥 Commits

Reviewing files that changed from the base of the PR and between b852bbf and 9ecc102.

📒 Files selected for processing (1)

• AGENTS.md

✅ Files skipped from review due to trivial changes (1)

• AGENTS.md

---

📝 Walkthrough

Walkthrough

This PR updates AGENTS.md by replacing “Guidelines” with a “Rules” section that expands compatibility and API-contract requirements, adds contributor toolchain and commit/changeset requirements, and updates References to point to docs/CONTRIBUTING.md. It also adds a new .changeset/agents-md-expand.md file documenting the edit.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• clerk/javascript#8566: Both PRs modify AGENTS.md and repository contribution/release guidance.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes—expanding AGENTS.md with toolchain, changeset, and commit rules—and is clear and specific about the PR's primary content.
Description check	✅ Passed	The description is directly related to the changeset, explaining the purpose of expanding AGENTS.md and linking to additional documentation, which aligns with the file changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8610

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8610

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8610

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8610

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8610

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8610

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8610

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8610

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8610

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8610

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8610

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8610

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8610

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8610

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8610

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8610

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8610

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8610

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8610

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8610

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8610

commit: 9ecc102

[alexcarpenter]

I added a bit more thorough reference docs here 0181046

curious your thoughts? encompasses a bit of what your adding here, but uses references vs adding them to the root agents file.

[jacekradko]

@alexcarpenter Didn't see that! Looks good. I am curious what that looks like per prompt. Not sure if LLMs auto resolve those references and send the full context with each prompt or not. Something we can optimize in the future though