feat(repo): add clerk-monorepo Claude Code skill#8769
Conversation
🦋 Changeset detectedLatest commit: ade1868 The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen 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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis PR introduces comprehensive developer guidance for the Clerk JavaScript SDK monorepo. A new Claude skill document defines setup, package structure, dev workflows, hard rules, and breaking-change detection. Three reference guides provide detailed breakdowns of breaking changes, package routing, and setup troubleshooting. Existing rule documents are updated with clarified requirements and integrated with the new skill. ChangesMonorepo Developer Guidance
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
jacekradko
force-pushed
the
jacek/clerk-monorepo-skill
branch
from
85ac2ef to
cc826e1
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (3)
.claude/skills/clerk-monorepo/references/package-map.md (3)
86-87: 💤 Low valueHyphenate "client-side" in compound modifier.
Line 86–87 uses "client side" but should be "client-side" when used as a compound adjective.
📝 Proposed fix
- **Next.js middleware / route handlers / server components**: `packages/nextjs/src` (client side - reuses `@clerk/react` unchanged). + **Next.js middleware / route handlers / server components**: `packages/nextjs/src` (client-side + reuses `@clerk/react` unchanged).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.claude/skills/clerk-monorepo/references/package-map.md around lines 86 - 87, Update the compound modifier in the sentence describing Next.js artifacts: change "client side reuses `@clerk/react` unchanged" to "client-side reuses `@clerk/react` unchanged" so "client-side" is hyphenated when used as an adjective; locate the phrase following "Next.js middleware / route handlers / server components" and replace "client side" with "client-side".
86-86: 💤 Low valueHyphenate "client-side" in compound modifier.
Line 86 uses "client side" but should be "client-side" when used as a compound adjective before a noun.
📝 Proposed fix
- `react`/`astro`/`vue`/`chrome-extension` adapters; its compiled runtime is delivered alongside + `react`/`astro`/`vue`/`chrome-extension` adapters; its compiled runtime is delivered alongsideActually, re-reading line 86-87:
`react`/`astro`/`vue`/`chrome-extension` adapters; its compiled runtime is delivered alongside `clerk-js` (both are backwards-compat sensitive), though `clerk-js` does not declare it as a packageThe phrase is in the middle of explaining that ui is consumed by adapters. Let me find the exact phrase. Looking at the context provided, line 86 context is:
- `react`/`astro`/`vue`/`chrome-extension` adapters; its compiled runtime is delivered alongsideSo "client side" would need to be in a different part. Let me look at the original again... Actually looking at the LanguageTool hint:
[grammar] ~86-~86: Use a hyphen to join words. Context: ...ponents**: `packages/nextjs/src` (client side reuses `@clerk/react` unchanged)....So it's on line 86 in the "Change X, touch Y" section under Next.js. The context shows "(client side reuses..." which should be "(client-side reuses...". Let me find where in the range this is. Looking at the provided code more carefully...
Looking at lines 86-87 in the provided code:
- **Next.js middleware / route handlers / server components**: `packages/nextjs/src` (client side reuses `@clerk/react` unchanged).So "client side" spans lines 86-87 and should be "client-side". Let me correct my comment.
Actually, let me revert and fix the comment properly:
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.claude/skills/clerk-monorepo/references/package-map.md at line 86, The phrase "client side" in the Next.js section should be hyphenated as "client-side"; update the text near the bullet "**Next.js middleware / route handlers / server components**: `packages/nextjs/src` (client side reuses `@clerk/react` unchanged)" to read "(client-side reuses `@clerk/react` unchanged)" so the compound modifier is grammatically correct.
52-61: ⚡ Quick winAdd language identifier to fenced code block.
Line 52 starts a code block (three backticks) without specifying a language. This should have a language identifier (e.g.,
```text) for consistency with Prettier formatting guidelines and markdown best practices.📝 Proposed fix
## Dependency shape -``` +```text `@clerk/shared` (≈20 dependents, the base of the pyramid)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.claude/skills/clerk-monorepo/references/package-map.md around lines 52 - 61, Add a language identifier to the fenced code block that begins with the three backticks before the ASCII diagram (the block containing "`@clerk/shared`", "`@clerk/react`", "`@clerk/backend`", "`@clerk/ui`", and "`@clerk/clerk-js`") by changing the opening fence to include a language token such as ```text so the block is consistently formatted for Prettier/Markdown; update only the opening backticks for that diagram block.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In @.claude/skills/clerk-monorepo/references/package-map.md:
- Around line 86-87: Update the compound modifier in the sentence describing
Next.js artifacts: change "client side reuses `@clerk/react` unchanged" to
"client-side reuses `@clerk/react` unchanged" so "client-side" is hyphenated
when used as an adjective; locate the phrase following "Next.js middleware /
route handlers / server components" and replace "client side" with
"client-side".
- Line 86: The phrase "client side" in the Next.js section should be hyphenated
as "client-side"; update the text near the bullet "**Next.js middleware / route
handlers / server components**: `packages/nextjs/src` (client side reuses
`@clerk/react` unchanged)" to read "(client-side reuses `@clerk/react`
unchanged)" so the compound modifier is grammatically correct.
- Around line 52-61: Add a language identifier to the fenced code block that
begins with the three backticks before the ASCII diagram (the block containing
"`@clerk/shared`", "`@clerk/react`", "`@clerk/backend`", "`@clerk/ui`", and
"`@clerk/clerk-js`") by changing the opening fence to include a language token
such as ```text so the block is consistently formatted for Prettier/Markdown;
update only the opening backticks for that diagram block.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 7d112dcf-56ec-4d08-840d-1393b0eb43b4
📒 Files selected for processing (8)
.changeset/clerk-monorepo-skill.md.claude/skills/clerk-monorepo/SKILL.md.claude/skills/clerk-monorepo/references/breaking-changes.md.claude/skills/clerk-monorepo/references/package-map.md.claude/skills/clerk-monorepo/references/setup-and-footguns.md.cursor/rules/development.mdc.cursor/rules/monorepo.mdcAGENTS.md
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/README.md:
- Line 22: The README's statement that edits to SKILL.md "take effect
immediately, including in already-running sessions" is incorrect; update the
sentence in README.md to clarify that the skill instruction is loaded when a
skill is invoked and edits to SKILL.md will not affect an already-invoked skill
until the skill is re-invoked or a new session is started, e.g., replace the
claim with wording that changes take effect after re-invoking the skill or
starting a new session so readers understand the SKILL.md is not refreshed
mid-session.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 311a363c-52dc-4e77-9b27-d853c1460f51
📒 Files selected for processing (2)
.claude/skills/README.mddocs/CONTRIBUTING.md
✅ Files skipped from review due to trivial changes (1)
- docs/CONTRIBUTING.md
| 4. Files under `references/` are read only when the loaded skill points at them, so deep-dive | ||
| content stays out of context until it is needed. | ||
|
|
||
| Edits to a `SKILL.md` take effect immediately, including in already-running sessions. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
ls -la .claude/skills || true
sed -n '1,80p' .claude/skills/README.md
nl -ba .claude/skills/README.md | sed -n '15,35p'Repository: clerk/javascript
Length of output: 2967
🌐 Web query:
Claude Code SKILL.md edits take effect already-running session re-read invoked skill content stays in session
💡 Result:
Claude Code features live change detection for SKILL.md files, which allows edits to take effect in an already-running session without requiring a full restart [1][2][3]. However, once a skill is invoked, its content is injected into the session as a single message and remains there for the duration of that session [1][2][3]. Claude Code does not re-read or refresh the SKILL.md file on subsequent turns within the same session after it has already been invoked [1][2][3]. Consequently, if you edit a SKILL.md file after having already triggered the skill during your current session, Claude will continue to use the version of the instructions it loaded during the initial invocation [1][3]. To ensure Claude uses the updated instructions, you must either start a new session or be aware that the changes will only apply if the skill is triggered for the first time after the file has been edited [1][2][3]. For changes to plugin-based skill components—such as hooks,.mcp.json, agents, or output-styles—you must use the /reload-plugins command to apply updates [1][2][3].
Citations:
- 1: https://code.claude.com/docs/en/skills.md
- 2: https://claude-code.mintlify.app/en/skills
- 3: https://code.claude.com/docs/en/skills
Clarify when SKILL.md edits apply during an active session.
.claude/skills/README.md line 22 claims edits apply immediately in already-running sessions, but Claude Code keeps the already-invoked skill instructions loaded for the session and doesn’t refresh the SKILL.md on subsequent turns; updates take effect after re-invoking the skill (or starting a new session).
🔧 Suggested wording
-Edits to a `SKILL.md` take effect immediately, including in already-running sessions.
+Edits to a `SKILL.md` take effect for new invocations; re-invoke the skill or start a new session to pick up changes.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Edits to a `SKILL.md` take effect immediately, including in already-running sessions. | |
| Edits to a `SKILL.md` take effect for new invocations; re-invoke the skill or start a new session to pick up changes. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/README.md at line 22, The README's statement that edits to
SKILL.md "take effect immediately, including in already-running sessions" is
incorrect; update the sentence in README.md to clarify that the skill
instruction is loaded when a skill is invoked and edits to SKILL.md will not
affect an already-invoked skill until the skill is re-invoked or a new session
is started, e.g., replace the claim with wording that changes take effect after
re-invoking the skill or starting a new session so readers understand the
SKILL.md is not refreshed mid-session.
1 participant
Claude Code had nothing repo-specific beyond the 16-line
AGENTS.md, while Cursor already has a full.cursor/rules/set. This adds the Claude Code counterpart: aclerk-monoreposkill that loads on demand for setup, picking which package to change, the dev loop, and changesets/commits.AGENTS.mdstays the authority on the rules; the skill restates them in actionable form and links back, with reference files for the things nothing documented before (setup footguns, the package map, and the clerk-js/ui breaking-change checklist).Worth scrutiny: the rule restatements in
SKILL.md. I grounded them incommitlint.config.ts,turbo.json, and the package manifests rather than the prose docs, which corrected a few things: it's 21 active packages not 27, commitlint runs on the PR title, anddocsis a type, not a scope (validated by running commitlint against sample titles).Companion edits are minimal: the two
.cursorrules get a stale-version fix (Node 18 / pnpm 9 to 24.15 / 10.33) and a typo fix so both surfaces agree, andAGENTS.mdgets a one-line pointer to the skill. Empty changeset since nothing here touches a published package.Summary by CodeRabbit
Documentation
Chores
Note: Internal developer-facing updates; no user-facing features.