Merged
Conversation
- Add five Convex skill packs with guidance, references, and icons - Register the skills for OpenAI and Claude agents - Refresh Convex AI guidance and workspace skill metadata
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughThis PR adds comprehensive documentation and configuration for five Convex agent skills covering component creation, migration handling, performance auditing, quickstart setup, and authentication. It establishes a skills registry, updates Convex dependency version, and creates symlink references across agent/Claude/skills directories. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
.agents/skills/convex-performance-audit/references/subscription-cost.md (1)
170-170: Consider rewording to avoid repetitive sentence structure.Three consecutive sentences begin with "Queries," which slightly affects readability.
📝 Suggested rewording
-Queries that only need `name` and `email` no longer re-run on every heartbeat. Queries that actually need online status fetch the heartbeat document explicitly. +Subscriptions that only need `name` and `email` no longer re-run on every heartbeat. When online status is needed, queries fetch the heartbeat document explicitly.Alternatively:
-Queries that only need `name` and `email` no longer re-run on every heartbeat. Queries that actually need online status fetch the heartbeat document explicitly. +Reads requiring only `name` and `email` won't re-run on every heartbeat. When online status is actually needed, queries explicitly fetch the heartbeat document.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/convex-performance-audit/references/subscription-cost.md at line 170, The three consecutive sentences in the paragraph starting with "Queries that only need `name` and `email`..." are repetitive; reword to vary sentence openings and improve flow by combining or restructuring them—for example, change one sentence to start with "Only queries needing online status..." or merge into "Queries needing only `name` and `email` no longer re-run on every heartbeat, while those that require online status explicitly fetch the heartbeat document." Update the text containing the exact phrases "Queries that only need `name` and `email`" and "Queries that actually need online status fetch the heartbeat document explicitly" accordingly..agents/skills/convex-performance-audit/references/hot-path-rules.md (1)
220-220: Consider hyphenating compound adjective.The phrase "high volume" would be more grammatically correct as "high-volume" when used as a compound adjective modifying "query."
📝 Proposed fix
- the list page only needs a subset of fields - source documents are large -- the query is high volume +- the query is high-volume🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/convex-performance-audit/references/hot-path-rules.md at line 220, Summary: The compound adjective "high volume" should be hyphenated as "high-volume." Fix: locate the sentence containing "high volume" (e.g., the line that reads "An 800 byte summary row is materially cheaper than a 3 KB full document on a hot page.") and replace "high volume query" with "high-volume query" (or hyphenate any other occurrences of "high volume" used as an adjective) to ensure correct compound-adjective usage..agents/skills/convex-setup-auth/references/clerk.md (1)
3-7: Optional: add a “Last verified” date for external auth docs/URLs.Given the number of vendor-specific URLs and setup steps, a small header note (e.g., “Last verified: 2026-04-09”) would help future maintainers identify staleness faster.
Also applies to: 41-57
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/convex-setup-auth/references/clerk.md around lines 3 - 7, Add a short "Last verified: YYYY-MM-DD" header line to the Clerk/Convex external docs section in .agents/skills/convex-setup-auth/references/clerk.md (near the top where the two official docs links are listed) and add the same "Last verified" date header to the other referenced block covering lines 41-57; update the date to the current verification date and keep the format consistent across both places so maintainers can quickly spot staleness..agents/skills/convex-create-component/references/advanced-patterns.md (1)
5-36: Consider adding a clarifying note about the component boundary.The function handle example correctly shows the pattern, but readers cross-referencing with the performance audit docs might benefit from a brief note clarifying that
ctx.runMutation(components.workpool.enqueue, ...)on line 16 represents the app calling INTO the component boundary—the context wherectx.runQuery/runMutationare required for component interaction.This would help distinguish "app code calling component functions" from "code inside components calling other functions."
📝 Optional clarification
Consider adding a brief note before or after the app-side example:
## Function Handles for callbacks When the app needs to pass a callback function to the component, use function handles. This is common for components that run app-defined logic on a schedule or in a workflow. +Note: The app must use `ctx.runMutation` to call across the component boundary (see line 16). This is the "component exception" to avoiding `ctx.runQuery/runMutation` overhead within the same module. + ```tsBased on learnings from the relevant code snippet highlighting that function-budget.md mentions "components require ctx.runQuery/ctx.runMutation" without clarifying the app-to-component boundary context.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/convex-create-component/references/advanced-patterns.md around lines 5 - 36, Add a short clarifying note explaining the component boundary: state that the app-side call in startJob uses ctx.runMutation(components.workpool.enqueue, ...) to invoke code inside the component (i.e., the component boundary), and that inside the component (e.g., in enqueue) you must use ctx.runQuery/ctx.runMutation when calling other component APIs; reference startJob, components.workpool.enqueue, enqueue, and ctx.runQuery/ctx.runMutation so readers understand which side requires those context helpers.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/skills/convex-setup-auth/references/convex-auth.md:
- Around line 1-143: This doc currently instructs greenfield Convex Auth setup
but will break repos already using third‑party auth (Clerk); add a prominent
top-of-file warning that this guide is only for new Convex Auth setups (not for
projects already using Clerk/Auth0/etc.), reference the repo-specific symbols to
check before following it (src/app/providers.tsx, ConvexProviderWithClerk,
ConvexProvider, convex/schema.ts, convex/auth.config.ts, and the
authTables/ConvexAuthProvider changes), and add either (a) a short migration
guide outline for switching from Clerk→Convex Auth or (b) a note recommending
running an auth-detection step (or separate skill) to detect Clerk before
surfacing these instructions.
---
Nitpick comments:
In @.agents/skills/convex-create-component/references/advanced-patterns.md:
- Around line 5-36: Add a short clarifying note explaining the component
boundary: state that the app-side call in startJob uses
ctx.runMutation(components.workpool.enqueue, ...) to invoke code inside the
component (i.e., the component boundary), and that inside the component (e.g.,
in enqueue) you must use ctx.runQuery/ctx.runMutation when calling other
component APIs; reference startJob, components.workpool.enqueue, enqueue, and
ctx.runQuery/ctx.runMutation so readers understand which side requires those
context helpers.
In @.agents/skills/convex-performance-audit/references/hot-path-rules.md:
- Line 220: Summary: The compound adjective "high volume" should be hyphenated
as "high-volume." Fix: locate the sentence containing "high volume" (e.g., the
line that reads "An 800 byte summary row is materially cheaper than a 3 KB full
document on a hot page.") and replace "high volume query" with "high-volume
query" (or hyphenate any other occurrences of "high volume" used as an
adjective) to ensure correct compound-adjective usage.
In @.agents/skills/convex-performance-audit/references/subscription-cost.md:
- Line 170: The three consecutive sentences in the paragraph starting with
"Queries that only need `name` and `email`..." are repetitive; reword to vary
sentence openings and improve flow by combining or restructuring them—for
example, change one sentence to start with "Only queries needing online
status..." or merge into "Queries needing only `name` and `email` no longer
re-run on every heartbeat, while those that require online status explicitly
fetch the heartbeat document." Update the text containing the exact phrases
"Queries that only need `name` and `email`" and "Queries that actually need
online status fetch the heartbeat document explicitly" accordingly.
In @.agents/skills/convex-setup-auth/references/clerk.md:
- Around line 3-7: Add a short "Last verified: YYYY-MM-DD" header line to the
Clerk/Convex external docs section in
.agents/skills/convex-setup-auth/references/clerk.md (near the top where the two
official docs links are listed) and add the same "Last verified" date header to
the other referenced block covering lines 41-57; update the date to the current
verification date and keep the format consistent across both places so
maintainers can quickly spot staleness.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: c1853875-2107-431e-be5a-e5dc339f73d6
⛔ Files ignored due to path filters (8)
.agents/skills/convex-create-component/assets/icon.svgis excluded by!**/*.svg.agents/skills/convex-migration-helper/assets/icon.svgis excluded by!**/*.svg.agents/skills/convex-performance-audit/assets/icon.svgis excluded by!**/*.svg.agents/skills/convex-quickstart/assets/icon.svgis excluded by!**/*.svg.agents/skills/convex-setup-auth/assets/icon.svgis excluded by!**/*.svgconvex/_generated/ai/ai-files.state.jsonis excluded by!**/_generated/**convex/_generated/ai/guidelines.mdis excluded by!**/_generated/**pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (37)
.agents/skills/convex-create-component/SKILL.md.agents/skills/convex-create-component/agents/openai.yaml.agents/skills/convex-create-component/references/advanced-patterns.md.agents/skills/convex-create-component/references/hybrid-components.md.agents/skills/convex-create-component/references/local-components.md.agents/skills/convex-create-component/references/packaged-components.md.agents/skills/convex-migration-helper/SKILL.md.agents/skills/convex-migration-helper/agents/openai.yaml.agents/skills/convex-migration-helper/references/migration-patterns.md.agents/skills/convex-migration-helper/references/migrations-component.md.agents/skills/convex-performance-audit/SKILL.md.agents/skills/convex-performance-audit/agents/openai.yaml.agents/skills/convex-performance-audit/references/function-budget.md.agents/skills/convex-performance-audit/references/hot-path-rules.md.agents/skills/convex-performance-audit/references/occ-conflicts.md.agents/skills/convex-performance-audit/references/subscription-cost.md.agents/skills/convex-quickstart/SKILL.md.agents/skills/convex-quickstart/agents/openai.yaml.agents/skills/convex-setup-auth/SKILL.md.agents/skills/convex-setup-auth/agents/openai.yaml.agents/skills/convex-setup-auth/references/auth0.md.agents/skills/convex-setup-auth/references/clerk.md.agents/skills/convex-setup-auth/references/convex-auth.md.agents/skills/convex-setup-auth/references/workos-authkit.md.claude/skills/convex-create-component.claude/skills/convex-migration-helper.claude/skills/convex-performance-audit.claude/skills/convex-quickstart.claude/skills/convex-setup-authAGENTS.mdpackage.jsonskills-lock.jsonskills/convex-create-componentskills/convex-migration-helperskills/convex-performance-auditskills/convex-quickstartskills/convex-setup-auth
Comment on lines
+1
to
+143
| # Convex Auth | ||
|
|
||
| Official docs: https://docs.convex.dev/auth/convex-auth | ||
| Setup guide: https://labs.convex.dev/auth/setup | ||
|
|
||
| Use this when the user wants auth handled directly in Convex rather than through a third-party provider. | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. Confirm the user wants Convex Auth specifically | ||
| 2. Determine which sign-in methods the app needs: | ||
| - magic links or OTPs | ||
| - OAuth providers | ||
| - passwords and password reset | ||
| 3. Ask whether the user wants local-only setup or production-ready setup now | ||
| 4. Read the Convex Auth setup guide before writing code | ||
| 5. Make sure the project has a configured Convex deployment: | ||
| - run `npx convex dev` first if `CONVEX_DEPLOYMENT` is not set | ||
| - if CLI configuration requires interactive human input, stop and ask the user to complete that step before continuing | ||
| 6. Install the auth packages: | ||
| - `npm install @convex-dev/auth @auth/core@0.37.0` | ||
| 7. Run the initialization command: | ||
| - `npx @convex-dev/auth` | ||
| 8. Confirm the initializer created: | ||
| - `convex/auth.config.ts` | ||
| - `convex/auth.ts` | ||
| - `convex/http.ts` | ||
| 9. Add the required `authTables` to `convex/schema.ts` | ||
| 10. Replace plain `ConvexProvider` wiring with `ConvexAuthProvider` | ||
| 11. Configure at least one auth method in `convex/auth.ts` | ||
| 12. Run `npx convex dev --once` or the normal dev flow to push the updated schema and generated code | ||
| 13. Verify the client can sign in successfully | ||
| 14. Verify Convex receives authenticated identity in backend functions | ||
| 15. If the user wants production-ready setup, make sure the same auth setup is configured for the production deployment as well | ||
| 16. Only add a `users` table and `storeUser` flow if the app needs app-level user records inside Convex | ||
|
|
||
| ## What This Reference Is For | ||
|
|
||
| - choosing Convex Auth as the default provider for a new Convex app | ||
| - understanding whether the app wants magic links, OTPs, OAuth, or passwords | ||
| - keeping the setup provider-specific while using the official Convex Auth docs for identity and authorization behavior | ||
|
|
||
| ## What To Do | ||
|
|
||
| - Read the Convex Auth setup guide before writing setup code | ||
| - Follow the setup flow from the docs rather than recreating it from memory | ||
| - If the app is new, consider starting from the official starter flow instead of hand-wiring everything | ||
| - Treat `npx @convex-dev/auth` as a required initialization step for existing apps, not an optional extra | ||
|
|
||
| ## Concrete Steps | ||
|
|
||
| 1. Install `@convex-dev/auth` and `@auth/core@0.37.0` | ||
| 2. Run `npx convex dev` if the project does not already have a configured deployment | ||
| 3. If `npx convex dev` blocks on interactive setup, ask the user explicitly to finish configuring the Convex deployment | ||
| 4. Run `npx @convex-dev/auth` | ||
| 5. Confirm the generated auth setup is present before continuing: | ||
| - `convex/auth.config.ts` | ||
| - `convex/auth.ts` | ||
| - `convex/http.ts` | ||
| 6. Add `authTables` to `convex/schema.ts` | ||
| 7. Replace `ConvexProvider` with `ConvexAuthProvider` in the app entry | ||
| 8. Configure the selected auth methods in `convex/auth.ts` | ||
| 9. Run `npx convex dev --once` or the normal dev flow so the updated schema and auth files are pushed | ||
| 10. Verify login locally | ||
| 11. If the user wants production-ready setup, repeat the required auth configuration against the production deployment | ||
|
|
||
| ## Expected Files and Decisions | ||
|
|
||
| - `convex/schema.ts` | ||
| - frontend app entry such as `src/main.tsx` or the framework-equivalent provider file | ||
| - generated Convex Auth setup produced by `npx @convex-dev/auth` | ||
| - an existing configured Convex deployment, or the ability to create one with `npx convex dev` | ||
| - `convex/auth.ts` starts with `providers: []` until the app configures actual sign-in methods | ||
|
|
||
| - Decide whether the user is creating a new app or adding auth to an existing app | ||
| - For a new app, prefer the official starter flow instead of rebuilding setup by hand | ||
| - Decide which auth methods the app needs: | ||
| - magic links or OTPs | ||
| - OAuth providers | ||
| - passwords | ||
| - Decide whether the user wants local-only setup or production-ready setup now | ||
| - Decide whether the app actually needs a `users` table inside Convex, or whether provider identity alone is enough | ||
|
|
||
| ## Gotchas | ||
|
|
||
| - Do not assume a specific sign-in method. Ask which methods the app needs before wiring UI and backend behavior. | ||
| - `npx @convex-dev/auth` is important because it initializes the auth setup, including the key material. Do not skip it when adding Convex Auth to an existing project. | ||
| - `npx @convex-dev/auth` will fail if the project does not already have a configured `CONVEX_DEPLOYMENT`. | ||
| - `npx convex dev` may require interactive setup for deployment creation or project selection. If that happens, ask the user explicitly for that human step instead of guessing. | ||
| - `npx @convex-dev/auth` does not finish the whole integration by itself. You still need to add `authTables`, swap in `ConvexAuthProvider`, and configure at least one auth method. | ||
| - A project can still build even if `convex/auth.ts` still has `providers: []`, so do not treat a successful build as proof that sign-in is fully configured. | ||
| - Convex Auth does not mean every app needs a `users` table. If the app only needs authentication gates, `ctx.auth.getUserIdentity()` may be enough. | ||
| - If the app is greenfield, starting from the official starter flow is usually better than partially recreating it by hand. | ||
| - Do not stop at local dev setup if the user expects production-ready auth. The production deployment needs the auth setup too. | ||
| - Keep provider-specific setup and Convex Auth authorization behavior in the official docs instead of inventing shared patterns from memory. | ||
|
|
||
| ## Production | ||
|
|
||
| - Ask whether the user wants dev-only setup or production-ready setup | ||
| - If the answer is production-ready, make sure the auth configuration is applied to the production deployment, not just the dev deployment | ||
| - Verify production-specific redirect URLs, auth method configuration, and deployment settings before calling the task complete | ||
| - Do not silently write a notes file into the repo by default. If the user wants rollout or handoff docs, create one explicitly. | ||
|
|
||
| ## Human Handoff | ||
|
|
||
| If `npx convex dev` or deployment setup requires human input: | ||
|
|
||
| - stop and explain exactly what the user needs to do | ||
| - say why that step is required | ||
| - resume the auth setup immediately after the user confirms it is done | ||
|
|
||
| ## Validation | ||
|
|
||
| - Verify the user can complete a sign-in flow | ||
| - Offer to validate sign up, sign out, and sign back in with the configured auth method | ||
| - If browser automation is available in the environment, you can do this directly | ||
| - If browser automation is not available, give the user a short manual validation checklist instead | ||
| - Verify `ctx.auth.getUserIdentity()` returns an identity in protected backend functions | ||
| - Verify protected UI only renders after Convex-authenticated state is ready | ||
| - Verify environment variables and redirect settings match the current app environment | ||
| - Verify `convex/auth.ts` no longer has an empty `providers: []` configuration once the app is meant to support real sign-in | ||
| - Run `npx convex dev --once` or the normal dev flow after setup changes and confirm Convex codegen and push succeed | ||
| - If production-ready setup was requested, verify the production deployment is also configured correctly | ||
|
|
||
| ## Checklist | ||
|
|
||
| - [ ] Confirm the user wants Convex Auth specifically | ||
| - [ ] Ask whether the user wants local-only setup or production-ready setup | ||
| - [ ] Ensure a Convex deployment is configured before running auth initialization | ||
| - [ ] Install `@convex-dev/auth` and `@auth/core@0.37.0` | ||
| - [ ] Run `npx convex dev` first if needed | ||
| - [ ] Run `npx @convex-dev/auth` | ||
| - [ ] Confirm `convex/auth.config.ts`, `convex/auth.ts`, and `convex/http.ts` were created | ||
| - [ ] Follow the setup guide for package install and wiring | ||
| - [ ] Add `authTables` to `convex/schema.ts` | ||
| - [ ] Replace `ConvexProvider` with `ConvexAuthProvider` | ||
| - [ ] Configure at least one auth method in `convex/auth.ts` | ||
| - [ ] Run `npx convex dev --once` or the normal dev flow after setup changes | ||
| - [ ] Confirm which sign-in methods the app needs | ||
| - [ ] Verify the client can sign in and the backend receives authenticated identity | ||
| - [ ] Offer end-to-end validation of sign up, sign out, and sign back in | ||
| - [ ] If requested, configure the production deployment too | ||
| - [ ] Only add extra `users` table sync if the app needs app-level user records |
There was a problem hiding this comment.
Critical: Convex Auth setup conflicts with existing Clerk integration.
This documentation instructs setting up Convex Auth (@convex-dev/auth), but the repository already uses Clerk authentication with a completely different architecture:
Existing Clerk setup (from relevant snippets):
src/app/providers.tsxusesClerkProvider+ConvexProviderWithClerk(notConvexProvider)convex/schema.tscontains only business tables (noauthTables)convex/auth.config.tsis configured for Clerk withNEXT_PUBLIC_CLERK_FRONTEND_API_URL
Conflicts with this guide:
- Lines 29, 60, 136: Instructs adding
authTablesto schema, but Clerk doesn't use authTables - Lines 30, 61, 137: Instructs replacing
ConvexProviderwithConvexAuthProvider, but the app usesConvexProviderWithClerk - Line 6: States "use this when the user wants auth handled directly in Convex rather than through a third-party provider," but Clerk is a third-party provider already integrated
Impact: Following these instructions would:
- Break the existing Clerk authentication
- Require a complete auth migration from Clerk to Convex Auth
- Duplicate or conflict with existing auth configuration files
Recommendations:
- Add a prominent warning at the top of this doc stating it's for new Convex Auth setup, not for apps already using Clerk/Auth0/other providers
- Consider adding a separate migration guide for switching from Clerk to Convex Auth if that's a supported workflow
- Alternatively, create a skill that detects the current auth provider before surfacing setup instructions
The documentation itself is technically correct for greenfield Convex Auth setup, but it's dangerous in this repository context.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/skills/convex-setup-auth/references/convex-auth.md around lines 1 -
143, This doc currently instructs greenfield Convex Auth setup but will break
repos already using third‑party auth (Clerk); add a prominent top-of-file
warning that this guide is only for new Convex Auth setups (not for projects
already using Clerk/Auth0/etc.), reference the repo-specific symbols to check
before following it (src/app/providers.tsx, ConvexProviderWithClerk,
ConvexProvider, convex/schema.ts, convex/auth.config.ts, and the
authTables/ConvexAuthProvider changes), and add either (a) a short migration
guide outline for switching from Clerk→Convex Auth or (b) a note recommending
running an auth-detection step (or separate skill) to detect Clerk before
surfacing these instructions.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
.agents/skills/so the skills can be surfaced consistently.Testing
Summary by CodeRabbit
New Features
Chores