feat(*): ship Clerk AGENTS.md rules for AI coding agents

.changeset/chrome-extension-agent-rules-vite.md

@@ -0,0 +1,14 @@
+---
+'@clerk/chrome-extension': minor
+---
+
+Add a Vite plugin that writes a Clerk section to the project's `AGENTS.md` when the Vite dev server starts under an AI coding agent, or in a repo that already has agent files such as `AGENTS.md` or `CLAUDE.md`, for extensions built with WXT, CRXJS, or a custom Vite setup. Nothing is written during builds, tests, or CI, and setting `CLERK_AGENTS_MD=false` turns it off.
+
+```ts
+// wxt.config.ts
+import { clerkChromeExtensionAgentRules } from '@clerk/chrome-extension/vite';
+
+export default defineConfig({
+  vite: () => ({ plugins: [clerkChromeExtensionAgentRules()] }),
+});
+```

.changeset/react-vue-agent-rules-vite.md

@@ -0,0 +1,15 @@
+---
+'@clerk/react': minor
+'@clerk/vue': minor
+---
+
+Add Vite plugins that write a Clerk section to the project's `AGENTS.md` when the Vite dev server starts under an AI coding agent, or in a repo that already has agent files such as `AGENTS.md` or `CLAUDE.md`. Nothing is written during builds, tests, or CI, and setting `CLERK_AGENTS_MD=false` turns it off.
+
+```ts
+import { clerkReactAgentRules } from '@clerk/react/vite';
+// or: import { clerkVueAgentRules } from '@clerk/vue/vite';
+
+export default defineConfig({
+  plugins: [react(), clerkReactAgentRules()],
+});
+```

.changeset/shared-agent-rules.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Add `@clerk/shared/agentRules`, `@clerk/shared/agentRulesWriter`, and `@clerk/shared/vite` for writing Clerk sections to a project's `AGENTS.md`. Add `isAgentEnvironment()` and `isClerkAgentRulesWriteAllowed()` to `@clerk/shared/utils`. `isClerkAgentRulesWriteAllowed()` returns `false` when `NODE_ENV=production`, in tests, in CI, or when `CLERK_AGENTS_MD=false`. Deployments that don't set `NODE_ENV=production` should set `CLERK_AGENTS_MD=false` to turn writes off.

.changeset/ship-sdk-agents-md.md

@@ -0,0 +1,19 @@
+---
+'@clerk/astro': patch
+'@clerk/backend': patch
+'@clerk/chrome-extension': patch
+'@clerk/clerk-js': patch
+'@clerk/electron': patch
+'@clerk/expo': patch
+'@clerk/express': patch
+'@clerk/fastify': patch
+'@clerk/hono': patch
+'@clerk/nextjs': patch
+'@clerk/nuxt': patch
+'@clerk/react': patch
+'@clerk/react-router': patch
+'@clerk/tanstack-react-start': patch
+'@clerk/vue': patch
+---
+
+Ship an `AGENTS.md` file in the package. It lists the current APIs for this version and recommends the Clerk plugin, so AI coding agents can read it from `node_modules` instead of relying on outdated training data.

.changeset/upgrade-agents-md.md

@@ -0,0 +1,5 @@
+---
+'@clerk/upgrade': minor
+---
+
+Add an `--agents-md` flag that writes Clerk sections to the project's `AGENTS.md` for each installed Clerk SDK, then exits. In a monorepo, it writes one section per app to the `AGENTS.md` at the repo root. Interactive upgrades also offer to write these sections. Nothing is written when `package.json` sets `"clerk": { "agentsMd": false }`.

.changeset/write-agents-md-in-dev.md

@@ -0,0 +1,14 @@
+---
+'@clerk/astro': minor
+'@clerk/electron': minor
+'@clerk/expo': minor
+'@clerk/express': minor
+'@clerk/fastify': minor
+'@clerk/hono': minor
+'@clerk/nextjs': minor
+'@clerk/nuxt': minor
+'@clerk/react-router': minor
+'@clerk/tanstack-react-start': minor
+---
+
+When your app runs in development and an AI coding agent such as Claude Code, Codex, Cursor, Gemini CLI, or GitHub Copilot is detected, or the repo already has agent files such as `AGENTS.md`, `CLAUDE.md`, `.claude/`, or `.cursor/`, Clerk now adds a Clerk section to the project's `AGENTS.md`, creating the file if needed. In a monorepo, the file is the one at the repo root, with one section per app. If you remove a section, Clerk doesn't add it back on that machine. To turn it off for one app, add `"clerk": { "agentsMd": false }` to that app's `package.json`. To turn it off for the whole repo, add it to the root `package.json`. Clerk then removes its sections on the next dev run. Each section tells the agent to read the installed `@clerk/<sdk>/AGENTS.md` before writing auth code and recommends the Clerk plugin (`npx plugins add clerk/skills`). Nothing is written when `NODE_ENV=production`, in tests, or in CI, and setting `CLERK_AGENTS_MD=false` turns it off. If your deployment doesn't set `NODE_ENV=production`, set `CLERK_AGENTS_MD=false` there. The section is written by the Astro and Nuxt dev servers, the Expo config plugin, the first `auth()` call or `clerkMiddleware()` request in Next.js, TanStack React Start's `clerkMiddleware()`, `clerkMiddleware()` in Express, Hono, and React Router, Fastify's `clerkPlugin`, and `createClerkBridge()` in an unpackaged Electron app.

.github/workflows/ci.yml

@@ -85,6 +85,9 @@ jobs:
       - name: Check Dashboard links
         run: pnpm lint:dashboard-links
 
+      - name: Check SDK AGENTS.md
+        run: pnpm lint:agents-md
+
       - name: Verify localizations are generated
         run: |
           pnpm --filter @clerk/localizations generate

.github/workflows/expo-native-build.yml

@@ -115,6 +115,7 @@ jobs:
           pnpm --filter @clerk/expo-google-signin pack --pack-destination "$SDK_PACK_DIR"
           pnpm --filter @clerk/expo-native-components pack --pack-destination "$SDK_PACK_DIR"
           pnpm --filter @clerk/expo-biometrics pack --pack-destination "$SDK_PACK_DIR"
+          pnpm --filter @clerk/shared pack --pack-destination "$SDK_PACK_DIR"
 
       - name: Install fixture dependencies
         if: steps.native-build-cache.outputs.cache-hit != 'true'
@@ -123,6 +124,8 @@ jobs:
           EXPO_SDK: ${{ matrix.expo-sdk }}
         run: |
           cp "package.sdk-$EXPO_SDK.json" package.json
+          SHARED_TARBALL="$(ls "$SDK_PACK_DIR"/clerk-shared-*.tgz)"
+          printf 'overrides:\n  "@clerk/shared": "file:%s"\n' "$SHARED_TARBALL" >> pnpm-workspace.yaml
           pnpm install --no-frozen-lockfile
           # [0-9] keeps this glob off the other clerk-expo-* tarballs.
           SDK_TARBALL="$(ls "$SDK_PACK_DIR"/clerk-expo-[0-9]*.tgz)"

.typedoc/__tests__/__snapshots__/clerk-properties.mdx

@@ -4,7 +4,7 @@
 | <a id="billing"></a> `billing`                     | [`BillingNamespace`](/docs/reference/objects/billing)                                                | The `Billing` object used for managing billing.                                                                                                                                                                                                                                                                                          |
 | <a id="client"></a> `client`                       | <code>undefined \| [ClientResource](/docs/reference/objects/client)</code>                           | The `Client` object for the current window.                                                                                                                                                                                                                                                                                              |
 | <a id="domain"></a> `domain`                       | `string`                                                                                             | The current Clerk app's domain. Prefixed with `clerk.` on production if not already prefixed. Returns `""` when ran on the server.                                                                                                                                                                                                       |
-| <a id="instancetype"></a> `instanceType`           | <code>undefined \| "production" \| "development"</code>                                              | Indicates whether the Clerk instance is running in a production or development environment.                                                                                                                                                                                                                                              |
+| <a id="instancetype"></a> `instanceType`           | <code>undefined \| "development" \| "production"</code>                                              | Indicates whether the Clerk instance is running in a production or development environment.                                                                                                                                                                                                                                              |
 | <a id="issatellite"></a> `isSatellite`             | `boolean`                                                                                            | Indicates whether the instance is a satellite app.                                                                                                                                                                                                                                                                                       |
 | <a id="issignedin"></a> `isSignedIn`               | `boolean`                                                                                            | Indicates whether the current user has a valid signed-in client session.                                                                                                                                                                                                                                                                 |
 | <a id="isstandardbrowser"></a> `isStandardBrowser` | <code>undefined \| boolean</code>                                                                    | Indicates whether the instance is being loaded in a standard browser environment. Set to `false` on native platforms where cookies cannot be set. When `undefined`, Clerk assumes a standard browser.                                                                                                                                    |

package.json

@@ -4,6 +4,7 @@
   "private": true,
   "license": "MIT",
   "scripts": {
+    "agents-md:sync": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON ./scripts/sync-agents-md.mjs",
     "build": "FORCE_COLOR=1 turbo build --concurrency=${TURBO_CONCURRENCY:-80%}",
     "build:declarations": "FORCE_COLOR=1 turbo build:declarations --concurrency=${TURBO_CONCURRENCY:-80%} --filter=@clerk/nextjs",
     "bundlewatch": "turbo run bundlewatch",
@@ -20,6 +21,7 @@
     "preinstall": "npx only-allow pnpm",
     "integration:secrets": "node ./scripts/1password-keys.mjs",
     "lint": "node ./scripts/lint.mjs",
+    "lint:agents-md": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON ./scripts/sync-agents-md.mjs --check",
     "lint:attw": "FORCE_COLOR=1 turbo lint:attw",
     "lint:dashboard-links": "node ./scripts/check-dashboard-links.mjs",
     "lint:fix": "FORCE_COLOR=1 turbo lint -- --fix",

packages/astro/AGENTS.md

@@ -0,0 +1,34 @@
+## Clerk + Astro
+
+Read the installed `@clerk/astro` types before changing auth code. If a symbol is not in those types, it does not exist.
+
+### Current APIs
+
+- Register the default export of `@clerk/astro` in `integrations` in `astro.config`. `server` output needs an adapter.
+- Use `clerkMiddleware()` from `@clerk/astro/server` in `src/middleware.ts`.
+- `createRouteMatcher()` was removed. Check auth in each page or API route with `Astro.locals.auth()` or `locals.auth()`, then call `redirectToSignIn()` or return a 401.
+- `locals.currentUser()` returns the Backend `User` or `null`.
+- `<SignedIn>`, `<SignedOut>`, and `<Protect>` were removed. Import `<Show>` from `@clerk/astro/components` (or `@clerk/astro/react`). Its `when` prop is required, for example `<Show when="signed-in">`.
+- The `as` prop was removed from `<SignInButton>`, `<SignUpButton>`, and `<SignOutButton>`. Use `asChild` with a child element.
+- Clerk Elements is removed. Never use it.
+
+<!-- BEGIN:clerk-plugin -->
+
+### Clerk plugin
+
+The Clerk plugin gives agents Clerk's skills and MCP server. If it is not installed, tell the user they can install it. Do not run the command yourself:
+
+```sh
+npx plugins add clerk/skills
+```
+
+Install steps for each tool: https://clerk.com/docs/guides/ai/overview
+Source: https://github.com/clerk/skills
+
+Ask the user before calling any Clerk tool that creates or changes something in their Clerk account.
+
+### Docs
+
+Start at https://clerk.com/docs/llms.txt. Add `.md` to any docs URL to get Markdown.
+
+<!-- END:clerk-plugin -->

packages/astro/package.json

@@ -67,6 +67,7 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
+    "AGENTS.md",
     "dist",
     "client",
     "server",

packages/astro/src/integration/__tests__/agent-rules.test.ts

@@ -0,0 +1,71 @@
+import type * as AgentRules from '@clerk/shared/agentRules';
+import { writeClerkAgentRules } from '@clerk/shared/agentRules';
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@clerk/shared/agentRules', async importOriginal => ({
+  ...(await importOriginal<typeof AgentRules>()),
+  writeClerkAgentRules: vi.fn(),
+}));
+
+const loadWriteAgentRulesOnce = async () => (await import('../agent-rules')).writeAgentRulesOnce;
+
+describe('writeAgentRulesOnce', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.mocked(writeClerkAgentRules).mockReset();
+    for (const name of automatedEnvironmentVariables) {
+      vi.stubEnv(name, '');
+    }
+    vi.stubEnv('CLERK_AGENTS_MD', '');
+    vi.stubEnv('NODE_ENV', 'development');
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('writes the Astro rules once per process', async () => {
+    const writeAgentRulesOnce = await loadWriteAgentRulesOnce();
+
+    writeAgentRulesOnce(new URL('file:///app/'));
+    writeAgentRulesOnce(new URL('file:///app/'));
+
+    expect(writeClerkAgentRules).toHaveBeenCalledTimes(1);
+    expect(writeClerkAgentRules).toHaveBeenCalledWith(expect.objectContaining({ cwd: '/app/', sdks: ['astro'] }));
+  });
+
+  it('skips in CI', async () => {
+    vi.stubEnv('CI', 'true');
+
+    (await loadWriteAgentRulesOnce())(new URL('file:///app/'));
+
+    expect(writeClerkAgentRules).not.toHaveBeenCalled();
+  });
+
+  it('skips in production', async () => {
+    vi.stubEnv('NODE_ENV', 'production');
+
+    (await loadWriteAgentRulesOnce())(new URL('file:///app/'));
+
+    expect(writeClerkAgentRules).not.toHaveBeenCalled();
+  });
+
+  it('skips when CLERK_AGENTS_MD is false', async () => {
+    vi.stubEnv('CLERK_AGENTS_MD', 'false');
+
+    (await loadWriteAgentRulesOnce())(new URL('file:///app/'));
+
+    expect(writeClerkAgentRules).not.toHaveBeenCalled();
+  });
+
+  it('does not throw when writing fails', async () => {
+    vi.mocked(writeClerkAgentRules).mockImplementation(() => {
+      throw new Error('EACCES');
+    });
+
+    const writeAgentRulesOnce = await loadWriteAgentRulesOnce();
+
+    expect(() => writeAgentRulesOnce(new URL('file:///app/'))).not.toThrow();
+  });
+});

packages/astro/src/integration/agent-rules.ts

@@ -0,0 +1,22 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { logClerkAgentRulesError, logClerkAgentRulesResult, writeClerkAgentRules } from '@clerk/shared/agentRules';
+import { isClerkAgentRulesWriteAllowed } from '@clerk/shared/utils';
+
+let didWrite = false;
+
+export function writeAgentRulesOnce(root: URL) {
+  if (didWrite || !isClerkAgentRulesWriteAllowed()) {
+    return;
+  }
+
+  didWrite = true;
+
+  try {
+    logClerkAgentRulesResult(writeClerkAgentRules({ cwd: fileURLToPath(root), fs, path, sdks: ['astro'] }));
+  } catch (error) {
+    logClerkAgentRulesError(error);
+  }
+}

packages/astro/src/integration/create-integration.ts

@@ -4,6 +4,7 @@ import { envField } from 'astro/config';
 
 import { name as packageName, version as packageVersion } from '../../package.json';
 import type { AstroClerkIntegrationParams } from '../types';
+import { writeAgentRulesOnce } from './agent-rules';
 import { buildBeforeHydrationSnippet, buildPageLoadSnippet } from './snippets';
 import { vitePluginAstroConfig } from './vite-plugin-astro-config';
 
@@ -31,6 +32,10 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
       name: '@clerk/astro/integration',
       hooks: {
         'astro:config:setup': ({ config, injectScript, updateConfig, logger, command }) => {
+          if (command === 'dev') {
+            writeAgentRulesOnce(config.root);
+          }
+
           if (['server', 'hybrid'].includes(config.output) && !config.adapter) {
             logger.error('Missing adapter, please update your Astro config to use one.');
           }

packages/backend/AGENTS.md

@@ -0,0 +1,32 @@
+## Clerk + Backend
+
+Read the installed `@clerk/backend` types before changing auth code. If a symbol is not in those types, it does not exist.
+
+### Current APIs
+
+- Create the client with `createClerkClient({ secretKey, publishableKey })` from `@clerk/backend`.
+- Authenticate a Fetch `Request` with `await clerkClient.authenticateRequest(request)`. Check `requestState.isAuthenticated`, not the deprecated `isSignedIn`, then read auth from `requestState.toAuth()`.
+- Verify machine tokens with `verify()`: `clerkClient.apiKeys.verify(secret)`, `clerkClient.m2m.verify(params)`, `clerkClient.idPOAuthAccessToken.verify(token)`. `verifySecret()`, `verifyAccessToken()`, and `m2m.verifyToken()` are removed. The top-level `verifyToken()` export still exists.
+- Verify webhooks with `verifyWebhook(request)` from `@clerk/backend/webhooks`. It reads `CLERK_WEBHOOK_SIGNING_SECRET` by default.
+- Clerk Elements is removed. Never use it.
+
+<!-- BEGIN:clerk-plugin -->
+
+### Clerk plugin
+
+The Clerk plugin gives agents Clerk's skills and MCP server. If it is not installed, tell the user they can install it. Do not run the command yourself:
+
+```sh
+npx plugins add clerk/skills
+```
+
+Install steps for each tool: https://clerk.com/docs/guides/ai/overview
+Source: https://github.com/clerk/skills
+
+Ask the user before calling any Clerk tool that creates or changes something in their Clerk account.
+
+### Docs
+
+Start at https://clerk.com/docs/llms.txt. Add `.md` to any docs URL to get Markdown.
+
+<!-- END:clerk-plugin -->

packages/backend/package.json

@@ -89,6 +89,7 @@
   },
   "main": "./dist/index.js",
   "files": [
+    "AGENTS.md",
     "dist",
     "errors",
     "internal",

packages/chrome-extension/AGENTS.md

@@ -0,0 +1,33 @@
+## Clerk + Chrome Extension
+
+Read the installed `@clerk/chrome-extension` types before changing auth code. If a symbol is not in those types, it does not exist.
+
+### Current APIs
+
+- Pass `publishableKey` to `<ClerkProvider>`. There is no env var fallback. Pass `syncHost` to sync sessions with your web app.
+- In the background service worker, use `createClerkClient()` from `@clerk/chrome-extension/background`. `__unstable__createClerkClient` was renamed.
+- `<SignedIn>`, `<SignedOut>`, and `<Protect>` were removed. Use `<Show when="signed-in">` or `<Show when="signed-out">`.
+- `<GoogleOneTap>` renders nothing in extensions.
+- The root `useSignIn()` and `useSignUp()` are the Core 3 hooks. The old `isLoaded`-style hooks are in `@clerk/chrome-extension/legacy`.
+- Clerk Elements is removed. Never use it.
+
+<!-- BEGIN:clerk-plugin -->
+
+### Clerk plugin
+
+The Clerk plugin gives agents Clerk's skills and MCP server. If it is not installed, tell the user they can install it. Do not run the command yourself:
+
+```sh
+npx plugins add clerk/skills
+```
+
+Install steps for each tool: https://clerk.com/docs/guides/ai/overview
+Source: https://github.com/clerk/skills
+
+Ask the user before calling any Clerk tool that creates or changes something in their Clerk account.
+
+### Docs
+
+Start at https://clerk.com/docs/llms.txt. Add `.md` to any docs URL to get Markdown.
+
+<!-- END:clerk-plugin -->

packages/chrome-extension/package.json

@@ -65,19 +65,31 @@
     "./types": {
       "types": "./dist/types/types/index.d.ts"
     },
+    "./vite": {
+      "import": {
+        "types": "./dist/types/vite.d.ts",
+        "default": "./dist/esm/vite.js"
+      },
+      "require": {
+        "types": "./dist/types/vite.d.ts",
+        "default": "./dist/cjs/vite.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
   "files": [
+    "AGENTS.md",
     "background",
     "client",
     "dist",
     "internal",
     "legacy",
     "react",
-    "types"
+    "types",
+    "vite"
   ],
   "scripts": {
     "build": "tsup",

packages/chrome-extension/src/vite.ts

@@ -0,0 +1,3 @@
+import { clerkAgentRulesVitePlugin } from '@clerk/shared/vite';
+
+export const clerkChromeExtensionAgentRules = () => clerkAgentRulesVitePlugin('chrome-extension');