Convex's official top-level agent skill — routes an agent to the right convex-* skill for the task and to a served capability catalogue that stays current without a reinstall.
Convex Auth Setup Skill
Convex's official skill for adding passkey or OAuth authentication to a Convex app — including the auth.config.ts wiring and a headless key-generation path that avoids the interactive wizard.
Install
Other ways to install
About
- Always writes auth.config.ts — the always-signed-out footgun
- Generates JWT_PRIVATE_KEY and JWKS headlessly with jose, no interactive wizard
- Sets env vars via the Convex MCP envSet tool or the NAME=VALUE CLI form
- Passkeys by default; password or OAuth only on explicit request
- Pre-installs shadcn/ui primitives the generated client code imports
- Verifies a real sign-in round-trips before finishing
This is a small skill that exists because of two specific failure modes, and it names both of them.
The first is auth.config.ts. Get it wrong or leave it out and a Convex app does not error — it is silently, permanently signed out, with nothing in the logs to explain why. The skill treats writing that file as a mandatory step rather than an optional one, which is the difference between a working sign-in and an afternoon of debugging.
The second is the setup wizard. npx @convex-dev/auth is interactive: it wants a login and a TTY, so it hangs in CI, in anonymous deployments and in any non-interactive agent run. Instead of instructing the agent to run it and hope, the skill generates JWT_PRIVATE_KEY and JWKS deterministically with jose — an extractable RS256 keypair, PKCS8 with newlines flattened to spaces, JWKS shaped as {keys:[{use:"sig", ...publicJwk}]} — and then sets the variables through the Convex MCP envSet tool or the NAME=VALUE CLI form. That last detail matters more than it looks: the private key starts with -----BEGIN, so the space-separated CLI form makes the tool parse the leading dash as an unknown flag.
The rest of the workflow installs @convex-dev/auth at a pinned build and registers it in convex.config.ts (with a note that pnpm will not hoist jose, so it has to be added explicitly), adds the provider in convex/auth.ts — passkeys by default, password or OAuth only on request — wires ConvexAuthProvider, the sign-in component and route guards on the client, and pre-installs any shadcn/ui primitive the generated code imports, because a missing @/components/ui/* is a hard build failure rather than a warning.
It also refuses to declare success on a green build: the last step is verifying that a real sign-in round-trips.
Part of Convex's official agent-skills set. Install with npx skills add get-convex/agent-skills --skill convex-auth.
Try it
Once installed, ask your agent something like:
Add passkey sign-in to this Convex app and wire the route guards — do it headlessly, I'm running in CI.
SKILL.md
The instructions your agent loads, as published by Convex.
Related Skills
See all Convex Auth Setup alternativesConvex's official skill for turning a one-sentence app idea into a running Next.js + Convex template with an anonymous dev deployment, plus strict rules for writing Convex functions that compile and push first time.
Skill: Convex Live Migrations
by Convex
Convex's official skill for changing the schema of a deployed app without breaking it — add the field optional, backfill with @convex-dev/migrations, verify, then tighten the validator.
Better Auth's official skill for hardening a Better Auth deployment: secret management, rate limiting, CSRF protection, trusted origins, session and cookie security, OAuth token encryption, IP tracking and audit logging.