Guide · Agent skill

How to use the Convex Component Builder agent skill

Updated 2026-11-02 · written with AI from the project's own documentation and checked against our catalogue data

The convex-create-component skill is an agent skill: a set of instructions and reference files that an AI coding agent loads when your request matches its purpose. Once it is installed, the agent follows a structured workflow for building reusable Convex backend modules with their own tables, functions and app-facing APIs. This guide explains what the skill does, how to install it, how to trigger it, and what to check before you use it.

Convex Component Builderopenclaw/clawhub · MIT Download the skill

Quick start

1Download and unzip the skill. Download the convex-create-component ZIP from this page and unzip it so the skill folder is in ~/.claude/skills/ or in your project's .claude/skills/ folder.
2Confirm your project is ready. Make sure you have Node.js, npm and an existing Convex project that you run with npx convex dev.
3Describe the component you need. Ask the agent in plain language for a reusable Convex component, and say whether it is for one app or several.
4Answer the agent's shape question. The agent will ask what you are building and pick local, packaged or hybrid. Local is the default if you are unsure.
5Review the plan. Check the tables the component owns, the public functions it exposes and the data passed in from the app before the agent writes files.
6Wire the component into the app. Let the agent add the component to convex/convex.config.ts with app.use and create app-side wrappers if clients need access.
7Run npx convex dev. Run npx convex dev and fix any codegen, type or boundary issues it reports before you consider the component finished.

What the skill makes the agent do

The skill guides the agent through creating a Convex component. Before writing code, it decides whether a component is justified at all. If the feature does not need isolated tables, backend functions or reusable persistent state, the skill steers the agent toward normal app code or a regular TypeScript library instead.

When a component is justified, the agent plans which tables the component owns, which public functions it exposes, what data must be passed in from the app (such as auth, environment variables or parent IDs), and what stays in the app as wrappers or HTTP mounts. It then creates the component's convex.config.ts, schema.ts and function files, wires the component into the main app with app.use, and runs npx convex dev to fix codegen, type and boundary issues.

Decides whether a component is worth creating
Plans tables, public functions and data passed across the boundary
Scaffolds config, schema and function files
Wires the component into the app with app.use
Writes app-side wrapper functions so clients never call component internals directly
Includes reference guides for local, packaged and hybrid layouts

Install the convex-create-component skill

Download the ZIP file for the skill from the page where you found this guide. Unzip it so that the skill folder sits in one of the skills locations below. The skill folder contains SKILL.md, an agents folder with openai.yaml, and a references folder with four Markdown guides.

For a personal install that works in every project, unzip the skill into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder so it applies only to that repository.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

Personal install: ~/.claude/skills/
Project install: .claude/skills/ inside your project
Claude apps: Settings → Capabilities → Skills, then upload

Check the requirements before you start

The skill assumes you already have a Convex project. It is written around Convex APIs and the npx convex dev command, so it will not help much if you do not use Convex. Example wrappers in the skill use @convex-dev/auth, so have that library ready if you follow those examples.

The skill runs scripts, so read the safety notes below before installing it.

Node.js and npm
An existing Convex project
Convex CLI, run with npx convex dev
Convex auth library (@convex-dev/auth) if you follow the example wrapper

Trigger the skill with a natural request

You do not need a special command. Describe what you want in plain language and mention a reusable component, module, integration or component boundary. The skill's description lists these triggers: new components, reusable backend modules, integrations, and component boundary work.

Say what the component is for and whether it is for one app or several. The skill will ask what you are building and what the end goal is, then pick a layout. If you are unsure, it defaults to a local component.

"Create a reusable Convex component for notifications in this app."
"Extract our email integration into a Convex component that owns its own tables."
"Package this Convex backend logic so I can share it across several apps."
"Review whether this feature should be a component or just normal app code."

Understand the three layouts

The skill offers three shapes. Local is the default and is for a component that lives in the current app. Packaged is for publishing or sharing a component across apps. Hybrid combines a local component with shared library code and is an advanced option the skill does not choose by default.

For a local component, the skill uses this layout inside convex/: a convex.config.ts at the top level, and a components folder holding each component with its own convex.config.ts, schema.ts and feature files.

Local: for this app only (default)
Packaged: publish or share across apps
Hybrid: local install plus shared library code, only when explicitly needed

convex/
  convex.config.ts
  components/
    <name>/
      convex.config.ts
      schema.ts
      <feature>.ts

Know the rules the skill enforces

The skill sets firm boundaries. Authentication and environment access stay in the app, because ctx.auth is not available inside components and component functions cannot read process.env. Parent app IDs cross the boundary as strings. Components are internal, so the app adds wrapper functions when clients need access.

Public component functions must have args and returns validators. Pagination uses paginator from convex-helpers, not .paginate(). HTTP routes are mounted in the app's convex/http.ts, not in the component.

Keep auth and env access in the app
Pass parent IDs as strings, not v.id() for app-owned tables
Import query, mutation and action from the component's own ./_generated/server
Put HTTP routes in the app's convex/http.ts
Use indexes instead of .filter() after a query

Wire the component into your app

Once the component's files exist, the app registers it in convex/convex.config.ts with defineApp and app.use. The app then calls the component through components.<name> with ctx.runQuery, ctx.runMutation or ctx.runAction. The path matches the file location, so a function in convex/components/notifications/lib.ts is called as components.notifications.lib.send.

Finish by running npx convex dev and fixing any codegen, type or boundary errors it reports.

import { defineApp } from "convex/server";
import notifications from "./components/notifications/convex.config.js";

const app = defineApp();
app.use(notifications);

export default app;

What people use it for

Building a notifications component that owns its own notifications table and exposes send and list functions to the app.
Extracting an integration's tables and workflows out of the main app so the logic stays separate from app code.
Packaging Convex backend functionality so the same component can be reused across several apps.
Reviewing whether a feature should be a component at all, before adding tables and boundaries to the project.

Frequently asked questions

How do I install the convex-create-component skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for a personal install, or into the project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings, then Capabilities, then Skills.

Is the convex-create-component skill free and what is its licence?

The skill is listed under the MIT licence. The source does not state any price, so check the page you downloaded it from for current terms.

What do I need to use the convex-create-component skill?

You need Node.js and npm, an existing Convex project, and the Convex CLI run with npx convex dev. If you follow the example wrapper, you also need the @convex-dev/auth library.

Does the skill run scripts or use the network?

The listing says the skill runs scripts and does not use the network. Review the skill files before installing, since scripts run on your machine.

When should I not use this skill?

Skip it for one-off business logic, thin utilities, or app-level orchestration that belongs in convex/. The skill itself advises against components in those cases and suggests a normal TypeScript library instead.

Why does the agent keep moving my code out of components or wrapping functions?

The skill enforces boundary rules: auth and environment access stay in the app, clients call app wrappers rather than component functions, and HTTP routes go in convex/http.ts. If codegen or type errors appear, npx convex dev reports them and the skill asks the agent to fix them before finishing.

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 build Convex apps and want to extract reusable backend logic such as notifications or integrations into a component with its own tables. Pick something else if you do not use Convex, or if your feature is simple enough to live in the main app or a plain TypeScript library, which the skill itself recommends in those cases.

Download the skill