Convex create component skill: build reusable Convex components

Source: convex/agent-skills · Maintainer: Convex · License: Apache-2.0 · Checked: 24 October 2026

What is the Convex create component skill?

The convex create component skill (convex-create-component) is Convex's official Agent Skill for building a reusable Convex component: a backend module with its own tables, its own functions and a small API that your app calls. It tells the agent how to pick the right shape, keep auth and secrets in the app, and wire everything up so it passes codegen.

Its SKILL.md description reads: "Builds reusable Convex components with isolated tables and app-facing APIs. Use for new components, reusable backend modules, integrations, or component boundary work."

It lives in convex/agent-skills, the same repo as the convex-quickstart skill. As of 24 October 2026, its skills.sh page listed 130.4K installs (snapshot, 24 October 2026), second only to convex-quickstart in the repo.

What is a Convex component, and when do you need one?

Convex's components overview calls components "like mini self-contained Convex backends" and says "They can't read your app's tables or call your app's functions unless you pass them in explicitly." The authoring docs describe them as a way to "package up Convex functions, schemas, and persistent state into a reusable module."

The skill is clear that a component is not always the answer. Its "When to Use" list covers:

• Creating a new component in an existing app
• Extracting reusable backend logic into a component
• Building a third-party integration that should own its own tables and workflows
• Packaging Convex functionality for reuse across apps

Its "When Not to Use" list rules out one-off business logic, thin utilities that don't need Convex tables or functions, app-level orchestration that belongs in convex/, and cases where a normal TypeScript library is enough.

What does the skill do?

The SKILL.md gives the agent a ten-step workflow:

1. Ask what you are building and what the end goal is, or confirm it if the repo already makes it obvious.
2. Choose a shape and read the matching reference file.
3. Decide whether a component is justified at all.
4. Plan the tables the component owns, the functions it exposes, the data the app must pass in (auth, env vars, parent IDs) and what stays in the app.
5. Create convex.config.ts, schema.ts and function files.
6. Import from the component's own ./_generated/server, not the app's.
7. Wire it into the app with app.use(...) in convex/convex.config.ts, creating that file if needed.
8. Call it from the app through components.<name> with ctx.runQuery, ctx.runMutation or ctx.runAction.
9. Add app wrapper functions for React clients, HTTP callers or public APIs.
10. Run npx convex dev and fix codegen, type or boundary issues.

Three shapes. A local component lives under convex/components/<componentName>/ and is the default. A packaged component is for publishing or sharing across apps. A hybrid is only for when you explicitly need local plus shared library code. The agent reads exactly one of the matching reference files: local-components.md, packaged-components.md or hybrid-components.md. A fourth file, advanced-patterns.md, covers function handles for callbacks, deriving validators from a schema, static configuration with a globals table and class-based client wrappers.

A worked skeleton. The SKILL.md includes a complete notifications component: its defineComponent config, a schema with an index, send and listUnread functions, the app's defineApp() wiring and an app-side wrapper that checks the signed-in user before calling components.notifications.lib.send.

Critical rules. These are the boundary rules agents most often get wrong:

• Keep authentication in the app, because ctx.auth is not available inside components.
• Keep environment access in the app.
• Pass parent app IDs as strings, and don't use v.id("parentTable") for app-owned tables inside the component.
• Don't expose component functions directly to clients; write app wrappers.
• Mount any component HTTP handlers in the app's convex/http.ts.
• Use indexes instead of .filter(), and put args and returns validators on every public component function.

Validation order. npx convex codegen --component-dir convex/components/<name>, then npx convex codegen, then npx convex dev. If validation stops on Convex login or deployment setup, the skill tells the agent to ask you for that exact step instead of guessing.

The folder holds SKILL.md, the four reference files, agents/openai.yaml (Codex display name "Convex Create Component" and a default prompt) and an icon.

How do you install it?

Just this skill. The command from skills.sh:

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

Pick from the set, or install all of them. From Convex's Agent Skills docs:

npx skills add convex/agent-skills
npx skills add convex/agent-skills --all

Convex's docs say skills install into .agents/skills/ in your project and are picked up by compatible agents, including Cursor, Claude Code and GitHub Copilot. Add -g to install for every project. For how Claude Code finds skills, see the Claude Code skills docs. For Codex and Cursor, see Codex skills and Cursor skills.

Component code still lives under convex/, so pairing this skill with convex-expert makes sense:

npx skills add https://github.com/convex/agent-skills --skill convex-create-component --skill convex-expert

How do you use it?

The repo README says skills apply automatically when the agent judges them relevant. To call one by hand, it lists /skill-name in Claude Code, Cursor and VS Code, $skill-name in Codex and @skill-name in Windsurf.

Example prompts (suggestions, not quotes from the repo):

• /convex-create-component Pull our rate limiting code into a local component with its own table.
• I want a Convex component for Slack notifications that I can reuse in two apps. Is a component the right call?
• Build a local audit-log component and wire it into convex.config.ts with app wrappers for the React client.
• Our component's codegen is failing after I added a v.id("users") argument. Fix the boundary.
• Turn this component into an npm package other Convex apps can install.

The second prompt should make the agent weigh step 3 first. The fourth should hit the IDs rule: parent IDs cross the boundary as v.string().

Tips and limits

• All three audits pass. On skills.sh, Gen Agent Trust Hub, Socket and Snyk all showed Pass on 24 October 2026.
• Check the docs for nuance. On environment variables, Convex's authoring docs say the system variables CONVEX_CLOUD_URL and CONVEX_SITE_URL are available in every component function, and that components can declare their own typed variables in convex.config.ts. The skill's simpler rule is to keep env access in the app.
• Pagination differs too. The skill says to use paginator from convex-helpers because .paginate() "does not work across the component boundary." The current docs say "The built-in .paginate() works in components," with the limit that "a query can only make one paginated call across all app and component runQuery calls," and point to stream from convex-helpers for more. If your agent follows the skill, it is the safer route, but the docs are the newer word.
• Fresh repos may not validate. The skill warns that codegen commands can fail until CONVEX_DEPLOYMENT is configured, and that components.<name> references won't typecheck until codegen runs.
• The README lags the folder. It lists six skills, three of which (convex-setup-auth, convex-migration-helper, convex-performance-audit) were removed from skills/ and still show on skills.sh. The Convex docs list matches the folder.

Under Apache 2.0 you can copy and modify the skill as long as you keep the license and notices and mark files you change.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box, and Kipt reads the SKILL.md with its reference files. Paste the repo link instead and Kipt shows the list of Convex skills to pick from, so you can add convex-expert in the same step. Your skills sit in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Convex.

Similar skills

• Convex quickstart skill: stands up a new Next.js and Convex app from a one-sentence idea.
• Convex expert skill: the rules for any code under convex/, which component code also needs.
• Convex skill: the router that sends an agent to the right Convex skill.
• Convex auth skill: adds sign-in, which the app must handle before calling a component.
• Codebase design skill: general guidance on module boundaries, outside Convex.