Convex Auth skill for Claude Code: add sign-in to a Convex app

Makes Claude add sign-in to a Convex app, with passkeys by default or password or OAuth like Google on request.

Installs: 38.6K; on skills.sh
Stars: 68; on GitHub
Updated: Oct 2026; last repo commit

Claude installs @convex-dev/auth and adds it to convex.config.ts, adds a provider in convex/auth.ts, writes convex/auth.config.ts, and wires the client with ConvexAuthProvider, a sign-in component and route guards. It then checks that a sign-in round-trips before it says it is done.

SKILL.md tells Claude not to run the interactive npx @convex-dev/auth wizard, because it hangs in non-interactive runs. Instead Claude generates the signing keys with a short Node script that uses jose, then sets JWT_PRIVATE_KEY, JWKS and SITE_URL on your deployment. The skill folder holds one file, SKILL.md.

Good for

Convex developers who need user sign-in in an existing app
People who got stuck on auth setup or signed-out loops with Convex
Teams running the setup in CI or other non-interactive sessions

Install convex-auth

Claude Code

Copy this prompt.

Install the convex-auth skill in Claude Code. Run this command:

npx skills add https://github.com/convex/agent-skills --skill convex-auth

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

Convex's docs say the skills CLI installs skills into .agents/skills/ in your project. The "All Convex skills" command installs every skill in the repo, which has 33 skill folders. One of them, convex-improve-convex-plugin, is listed in the Convex docs as sending your coding session's transcript to the Convex team. Run this skill with /convex-auth in Claude Code or $convex-auth in Codex, or let the agent pick it when the task fits.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Add authentication (passkeys/OAuth) to the current Convex app, including the auth.config.ts wiring.

Sections in SKILL.md

Workflow
Rules

Key facts

Author: Convex (the vendor's own repo; Convex's docs list it among the skills it provides)
Repo: convex/agent-skills
License: Apache-2.0 (LICENSE file; the README says original content is Apache-2.0)
Installs on skills.sh: 38,648 (Nov 2, 2026)
GitHub stars: 68 (Nov 2, 2026)
Last commit to the repo: Oct 29, 2026
What installs: 1 file: SKILL.md
Needs: A Convex app; installs @convex-dev/auth and sets JWT_PRIVATE_KEY, JWKS and SITE_URL on a deployment
Works in: Claude Code, Cursor, VS Code with GitHub Copilot, Windsurf, Codex (README lists how to invoke skills in each)
skills.sh audits: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass

What it includes

Installs @convex-dev/auth and adds it to convex.config.ts
SKILL.md says to use a pinned build. With pnpm it also runs pnpm add jose, because jose will not hoist otherwise.
Runs code · Install and register
Adds Passkey by default, or Password or OAuth like Google on request
The provider goes in convex/auth.ts. Claude only switches from passkeys when you ask.
Write · Add a provider
Creates JWT_PRIVATE_KEY and JWKS with a Node script using jose
The script writes them to .auth-keys.json. Claude sets them on the deployment, preferring the Convex MCP envSet tool, or the NAME=VALUE form of npx convex env set, then deletes the file.
Runs code · Generate keys without the wizard
Writes the file whose absence leaves the app silently signed out
SKILL.md calls it the number one real-world auth footgun: a missing or wrong auth.config.ts means the app is always signed out with no error.
Write · Write auth.config.ts
Adds ConvexAuthProvider, a sign-in component and route guards
If the UI imports shadcn/ui parts such as button or input, Claude adds them first with npx shadcn@latest add, since a missing @/components/ui file breaks the build.
Runs code · Wire the client
Checks that a sign-in actually round-trips before it finishes
This is the last step in the workflow.
Verify a sign-in

From the official docs

Permissions

Medium risk

Claude creates a private signing key, sets it on a Convex deployment and edits your sign-in code, so a wrong target or a leftover key file is a real exposure. Use a dev deployment and confirm .auth-keys.json is deleted before you commit.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It creates your signing key on disk first
A Node script writes the private key to .auth-keys.json, and SKILL.md has Claude delete it afterward. Check it is gone and not committed. github.com
It sets env vars on a deployment
JWT_PRIVATE_KEY, JWKS and SITE_URL are set through the Convex MCP envSet tool or npx convex env set. Make sure the target is the deployment you mean. github.com
It installs packages
It installs @convex-dev/auth (a pinned build), jose with pnpm, and shadcn/ui parts with npx shadcn@latest add. Read each command before you approve it. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No read-only mode. Auth setup writes keys and config by design.
Sign-in and keys	JWT_PRIVATE_KEY and JWKS are set as Convex deployment environment variables. A temporary .auth-keys.json holds them until Claude deletes it.
Scopes	Installs @convex-dev/auth, plus jose with pnpm, and shadcn/ui components if the UI needs them Writes convex/auth.ts, convex/auth.config.ts and client sign-in code Creates .auth-keys.json with a private key, then sets env vars on the deployment

Questions

How do I install convex-auth?

Use the install box above. The skill is a single SKILL.md. Run it with /convex-auth in Claude Code or $convex-auth in Codex. The Convex docs use the same command as their example for kicking off auth setup.

Which sign-in methods does it set up?

Passkeys by default. SKILL.md says it adds Password or OAuth such as Google only on an explicit request.

Why does it skip the interactive auth wizard?

SKILL.md says the interactive npx @convex-dev/auth wizard needs a login and a terminal, and it hangs in non-interactive, anonymous or CI runs. Claude generates the keys itself with a small script instead.

What does it put on my deployment?

JWT_PRIVATE_KEY and JWKS, plus SITE_URL set to your dev URL, for example http://localhost:3000. Our advice: point it at a dev deployment, and check that .auth-keys.json is gone and was never committed.

Is it safe?

It generates a private signing key on disk, sets it on a deployment, installs packages and edits your auth and client code. SKILL.md has Claude delete the key file afterward. Use a dev deployment, review the diff, and confirm .auth-keys.json is gone before you commit.

Is it official?

Yes. It is in Convex's own agent-skills repo, and Convex's docs list it among the agent skills Convex provides.

Does it work in the Claude app?

The README and Convex docs name Claude Code, Cursor, VS Code with GitHub Copilot, Windsurf and Codex. They do not name the Claude app, and this skill works on a local project, so we list no Claude app install.

Information

updated Nov 2, 2026

Repository: convex/agent-skills
Folder: skills/convex-auth

convex/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 3

convex/agent-skills README · github.com
Convex docs: Agent Skills · docs.convex.dev
convex-auth SKILL.md · github.com