Convex Create Component skill for Claude Code: build reusable backend components

• Checks the work needs its own tables or functions before building a component

  SKILL.md says not to use a component for one-off business logic, thin utilities, app-level orchestration, or cases where a normal TypeScript library is enough.

  Decide if a component fits

• Local by default, packaged for npm, hybrid only if you explicitly ask

  Claude reads exactly one of references/local-components.md, packaged-components.md or hybrid-components.md after you confirm the goal.

  Read · Choose the shape

• Lists the tables, public functions and data the app must pass in

  The plan covers what tables the component owns, what functions it exposes, what the app passes in (auth, env vars, parent IDs), and what stays in the app as wrappers or HTTP mounts.

  Plan the boundary

• Creates convex.config.ts, schema.ts and function files, then app.use(...)

  The component imports from its own ./_generated/server. The app calls it through components.<name> with ctx.runQuery, ctx.runMutation or ctx.runAction.

  Write · Build and wire the component

• Ten rules for auth, env, IDs, wrappers, HTTP routes, pagination and indexes

  Auth and env access stay in the app. Parent IDs cross as strings. Clients get app wrappers, not component functions. Component HTTP routes are mounted in the app, and pagination uses paginator from convex-helpers.

  Critical rules

• Runs npx convex codegen with --component-dir, then codegen, then npx convex dev

  If validation blocks on Convex login or deployment setup, SKILL.md says to stop and ask you for that exact step.

  Runs code · Validate

• Function handles, validators from schema, a globals table, class wrappers

  references/advanced-patterns.md has four sections: function handles for callbacks, deriving validators from schema, static configuration with a globals table, and class-based client wrappers.

  Read · Advanced patterns reference

• Codex display name, default prompt and a switch that lets Codex start it itself

  The file sets allow_implicit_invocation to true and a default prompt that asks to check a component is justified before designing it.

  agents/openai.yaml

Watch out for

• It edits your Convex config and creates files

  It creates convex/convex.config.ts if missing and adds app.use(...) to it. Review the diff before you commit. github.com

• It runs npx convex dev against your project

  Validation ends with npx convex dev, which needs CONVEX_DEPLOYMENT set. Check which deployment that points to first. github.com

• The packaged route scaffolds with a create command

  references/packaged-components.md prefers npx create-convex@latest --component when possible. Approve it only if you want an npm package. github.com

Security advisories