Guide · Agent skill
How to use the Add sign-in to Convex app agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The convex-auth skill is a set of instructions that an AI agent (such as Claude) loads so it can add user sign-in to a Convex web app. It covers installing @convex-dev/auth, adding a sign-in provider, generating signing keys, writing the auth config file, wiring up the client UI, and checking that sign-in works. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what to check afterwards.
Add sign-in to Convex appopenclaw/clawhub · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it so that SKILL.md sits in a convex-auth folder.
- 2Place the folder. Move the folder into ~/.claude/skills/ for all projects, or into your project's .claude/skills/ folder. Alternatively, upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Open your Convex project. Start the agent in a Convex web app that has a deployment set up.
- 4Ask for sign-in in plain language. Request passkey sign-in, or name password or Google OAuth if you want those instead.
- 5Review the commands. Check the key generation and environment variable commands before you approve them, since the skill runs scripts and uses the network.
- 6Test the sign-in. Create an account, sign out and sign back in to confirm that the session persists and protected pages work.
What is an agent skill, and what does convex-auth make the agent do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a request matches the skill's description. The convex-auth skill is named convex-auth and its description is: add authentication (passkeys/OAuth) to the current Convex app, including the auth.config.ts wiring.
When it applies, the agent follows a six-step workflow: install @convex-dev/auth and add it to convex.config.ts; add a provider in convex/auth.ts (Passkey by default, or Password or OAuth such as Google on request); generate the auth keys headlessly; write convex/auth.config.ts; wire the client with ConvexAuthProvider, a sign-in component and route guards; and verify that a sign-in round-trips before finishing.
- Passkeys are the default provider. Password or OAuth is used only when you explicitly ask for it.
- The skill avoids the interactive npx @convex-dev/auth setup wizard, which needs a terminal and can hang in non-interactive or CI runs.
- The skill warns that a missing or incorrect auth.config.ts leaves the app silently always signed out, with no error.
How do you install the convex-auth skill?
Download the ZIP for the skill from this page and unzip it. The package contains SKILL.md. Put the unzipped folder in one of these locations, depending on whether you want it for all projects or one project:
- Personal (all projects): ~/.claude/skills/
- Single project: the .claude/skills/ folder inside your project
- Claude apps: upload the ZIP under Settings → Capabilities → Skills
How do you trigger the skill with a natural request?
You do not need to type the skill name. Describe what you want in plain language while working in a Convex project. Requests that match the skill's purpose include adding login, sign-up, passkeys or Google sign-in to the app. Mention Convex so the agent knows which stack you use.
Be explicit if you want something other than the default. The skill uses passkeys unless you ask for password or OAuth such as Google.
- "Add passkey sign-in to this Convex app."
- "Add Google OAuth login to my Convex project, and wire up the auth.config.ts."
- "Set up user accounts in this Convex app. Use password sign-in instead of passkeys."
What does the skill need before it runs?
The skill lists its requirements. Check these before you start, because the instructions assume them.
- Node.js and npm or pnpm
- A Convex project and deployment
- The jose npm package, which the skill installs
- Convex CLI or the Convex MCP server, used to set environment variables
- shadcn/ui CLI, only if the UI imports shadcn components
What should you check for safety, scripts and network use?
This skill runs scripts and uses the network. It generates signing keys with a Node.js command and sets the variables JWT_PRIVATE_KEY, JWKS and SITE_URL on your Convex deployment. The skill deletes the .auth-keys.json file it creates after use.
The skill is not a substitute for a security review. Its own description says the result still needs human review of auth configuration and secret handling before production use. Read the commands the agent proposes before approving them.
- Keys are generated locally with the jose package and written to .auth-keys.json, which is removed afterwards.
- Use the MCP envSet tool or the NAME=VALUE form of npx convex env set, so multi-line keys are not mangled by the shell.
- SITE_URL is set to the development URL, for example http://localhost:3000, in the instructions.
What do you get, and how do you confirm it works?
The skill expects the agent to finish with a working sign-in. Ask it to test the flow and report the result. Then check the outcome yourself: create a test account, sign out, and sign back in. Confirm that the signed-in state appears in the UI and that protected routes behave correctly.
- Check that convex/auth.config.ts exists and matches your project.
- Check that the environment variables are set on the deployment.
- Check that the shadcn/ui components you import are present under @/components/ui/.
What people use it for
- Adding passkey sign-in to a new Convex web app so users can create accounts without passwords.
- Adding Google OAuth login to an existing Convex project alongside its current data model.
- Automating auth setup in a CI or non-interactive environment, where the interactive wizard cannot run.
- Wiring convex/auth.config.ts correctly so a Convex app does not stay silently signed out.
Frequently asked questions
How do I install the convex-auth skill?
Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for all projects, or in your project's .claude/skills/ folder for one project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What are the requirements for the convex-auth skill?
You need Node.js with npm or pnpm, a Convex project and deployment, and the Convex CLI or Convex MCP server to set environment variables. The skill installs the jose npm package. If your UI imports shadcn components, you also need the shadcn/ui CLI.
Does the convex-auth skill work for projects that do not use Convex?
No. The steps assume Convex and its deployment tooling, so the instructions will not apply to other stacks.
Is the convex-auth skill free, and what licence does it use?
The skill is listed under the MIT licence. Check the repository for the licence text itself.
Why does the skill avoid the npx @convex-dev/auth wizard?
The wizard needs a login or terminal, and according to the skill it hangs in non-interactive, anonymous or CI runs. The skill generates the JWT_PRIVATE_KEY and JWKS values with jose instead.
What should I do if my app always shows as signed out?
The skill's notes say a missing or incorrect convex/auth.config.ts causes the app to stay silently signed out with no error. Check that the file exists and matches your project, then verify that the environment variables are set on your deployment and test a sign-in again.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are building a Convex web app that needs user accounts and you want an agent to follow a tested, step-by-step setup. Pick something else if your project does not use Convex, or if you need a production security review, since the result still needs human review of auth configuration and secret handling.
Download the skill