Guide · Agent skill
How to use the Convex Auth Setup agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The convex-setup-auth skill is a set of instructions and reference files that teaches an AI agent how to add authentication to a Convex backend app. It is for developers who want login and protected backend functions, and for teams already using Clerk, Auth0 or WorkOS with Convex. After following this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what to check before and after it runs.
Convex Auth Setupopenclaw/clawhub · MIT Download the skill Quick start
- 1Download and unzip. Download the convex-setup-auth ZIP from this page and unzip it to get the skill folder.
- 2Place the skill folder. Copy the folder into ~/.claude/skills/ for personal use, or into your project's .claude/skills/ folder. Alternatively, upload it in the Claude apps under Settings → Capabilities → Skills.
- 3Open your Convex project. Start the agent in a Convex project so it can read your files and see whether a provider is already in use.
- 4Ask for auth in plain language. Request login or protected functions, and name a provider if you have one in mind.
- 5Answer the agent's questions. Choose the provider and decide between local-only and production-ready setup when asked.
- 6Complete the human steps. Finish any dashboard, provider account or deployment steps the agent asks you to do, then let it continue.
- 7Validate the result. Check that login works, that protected queries reject signed-out callers, and that environment variables are set.
What the skill makes the agent do
When the skill is installed, the agent follows a structured process for adding authentication to a Convex app. It first asks which auth provider to use (Convex Auth, Clerk, WorkOS AuthKit, Auth0, or a custom JWT provider), or infers the provider from the repository. It then reads the matching reference file and the official docs before wiring up packages, environment variables and configuration.
The skill also steers the agent toward checking identity on the server, inside backend functions, rather than trusting a user ID sent by the client.
- Chooses or confirms the auth provider before writing setup code
- Reads the matching local reference file (for example references/clerk.md) and the official provider docs
- Covers packages, client provider wiring, environment variables and convex/auth.config.ts
- Adds identity checks such as ctx.auth.getUserIdentity() to protected functions, with clear errors like "Not authenticated" and "Unauthorized"
Install the convex-setup-auth skill
Download the skill ZIP from this page and unzip it. For a personal setup, place the folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
The folder should contain SKILL.md, a references/ folder with the four provider files, and agents/openai.yaml.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with natural requests
You do not need a special command. The skill's description mentions login, auth providers, users tables, protected functions and roles in a Convex app, so ask in those terms. Name a provider if you already know which one you want; otherwise the agent will ask.
- "Add login to my Convex app using Clerk."
- "Set up Convex Auth with magic links for this project."
- "Make my Convex queries check that the caller is signed in."
- "Add an owner check so users can only edit their own documents in this mutation."
- "Help me wire up WorkOS AuthKit with my Convex React app."
What to expect during a setup
The skill is built to pause. It asks whether you want local-only setup or production-ready setup, and it stops for human steps such as dashboard configuration, deployment setup or provider account actions. For UI sign-up or sign-in flows, it offers to validate the flow in a browser if the environment supports it, or gives you a short manual checklist.
After running provider initialization commands, the agent is expected to check the generated files and finish the post-init wiring the provider reference lists. Initialization commands rarely complete the whole integration on their own.
- Expect questions about provider and local versus production setup
- Have your provider account and dashboard ready for human steps
- Expect a manual validation checklist if no browser automation is available
Example of the protected-function pattern
The core pattern is to read the user's identity on the server rather than accepting a user ID from the client. The skill's guidance contrasts a query that takes a client-provided userId argument with one that calls ctx.auth.getUserIdentity() and looks up the user by tokenIdentifier.
export const getMyProfile = query({
args: {},
handler: async (ctx) => {
const identity = await ctx.auth.getUserIdentity();
if (!identity) throw new Error("Not authenticated");
return await ctx.db
.query("users")
.withIndex("by_tokenIdentifier", (q) =>
q.eq("tokenIdentifier", identity.tokenIdentifier),
)
.unique();
},
});What you need before you start
You need a Convex project. For the human steps you need access to the account and dashboard of the provider you choose, such as Clerk, Auth0 or WorkOS. The skill also needs network access so it can read the official provider and Convex documentation.
- A Convex project
- An account and dashboard for your chosen provider (Clerk, Auth0, WorkOS or Convex Auth setup)
- Network access to official provider and Convex documentation
Safety notes: scripts and network access
This skill does not run scripts. It does use the network, because it reads official provider and Convex documentation during setup. Some provider guidance may suggest installing provider command-line tools, such as the Auth0 CLI, but the skill asks before doing so. Review any commands the agent proposes before you approve them, and check that production configuration is handled by you in the provider dashboard.
- Runs scripts: no
- Uses network: yes, to read official documentation
- Asks before installing provider CLIs such as the Auth0 CLI
What people use it for
- Adding sign-in to a new Convex React or Next.js app with a provider of your choice
- Adding a getUserIdentity check to queries and mutations that should only work for signed-in users
- Adding owner or role checks so users can only change their own documents or team data
- Integrating an existing Clerk, Auth0 or WorkOS setup with Convex backend functions
- Setting up Convex Auth with magic links, OAuth or passwords, as described in its reference file
Frequently asked questions
How do I install the convex-setup-auth skill?
Download the skill ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder for one project. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
What do I need to use this skill?
You need a Convex project, access to the account and dashboard of the auth provider you pick (such as Clerk, Auth0 or WorkOS) for the human steps, and network access so the agent can read official documentation. The skill does not run scripts.
Is the convex-setup-auth skill free?
The source gives the licence as MIT. It does not state pricing for the skill itself, and any costs for the auth provider you choose are set by that provider.
Does the skill set up authentication fully automatically?
No. The skill intentionally pauses to ask which provider to use, whether you want local-only or production-ready setup, and for human steps like dashboard or deployment configuration.
Which auth providers does the skill support?
It supports Convex Auth, Clerk, WorkOS AuthKit, Auth0, and a custom JWT provider. If the repository already uses a provider, the agent continues with that one unless you ask to switch.
Can I use this skill with a non-Convex backend?
No. The guidance is specific to Convex functions and config, and the skill's own list of when not to use it includes auth for a non-Convex backend.
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
This skill suits developers starting a Convex app who need login and protected backend functions, and teams already on Clerk, Auth0 or WorkOS who want guided integration. If you expect a one-click setup or use a different backend, pick another approach, because the skill pauses for choices and human steps and is tied to Convex.
Download the skill