Convex Create Component

What it does

When your agent uses it

• Reusable backend modules
• Component boundary work

Example prompts

• “Use the convex-create-component skill to build reusable Convex components with isolated tables and app-facing APIs”
• “/convex-create-component”

Requirements

• Node.js
• A credential in OPENAI_API_KEY

Workflow steps

10 steps, taken from the first numbered list in SKILL.md.

1. 1Ask the user what they are building and what the end goal is. If the repo
2. 2Choose the shape using the decision tree below and read the matching
3. 3Decide whether a component is justified. Prefer normal app code or a regular
4. 4Make a short plan for
5. 5Create the component structure with convex.config.ts, schema.ts, and
6. 6Implement functions using the component's own ./_generated/server imports,
7. 7Wire the component into the app with app.use(...). If the app does not
8. 8Call the component from the app through components. using
9. 9If React clients, HTTP callers, or public APIs need access, create wrapper
10. 10Run npx convex dev and fix codegen, type, or boundary issues before

What it can do on your machine

Read from SKILL.md and the folder at commit 665a13f. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • npx

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • docs.convex.dev

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • OPENAI_API_KEY

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Convex Create Component loads about 2.6k tokens when it runs, and up to ~4.5k if it reads all its reference files. Until then it costs about 48 tokens; SKILL.md has 802 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~48

When it runs · the whole SKILL.md, loaded when a task matches

~2.6k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~4.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from spokvulcan/poker-planning at commit 665a13f, republished under its MIT licence (© spokvulcan). 802 words, ~2,610 tokens.

name

convex-create-component

description

Builds reusable Convex components with isolated tables and app-facing APIs. Use for new components, reusable backend modules, integrations, or component boundary work.

// convex/components/notifications/convex.config.ts
import { defineComponent } from "convex/server";

export default defineComponent("notifications");

// convex/components/notifications/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  notifications: defineTable({
    userId: v.string(),
    message: v.string(),
    read: v.boolean(),
  }).index("by_user", ["userId"]),
});

// convex/components/notifications/lib.ts
import { v } from "convex/values";
import { mutation, query } from "./_generated/server.js";

export const send = mutation({
  args: { userId: v.string(), message: v.string() },
  returns: v.id("notifications"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("notifications", {
      userId: args.userId,
      message: args.message,
      read: false,
    });
  },
});

export const listUnread = query({
  args: { userId: v.string() },
  returns: v.array(
    v.object({
      _id: v.id("notifications"),
      _creationTime: v.number(),
      userId: v.string(),
      message: v.string(),
      read: v.boolean(),
    }),
  ),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("notifications")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .filter((q) => q.eq(q.field("read"), false))
      .collect();
  },
});

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

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

export default app;

// convex/notifications.ts  (app-side wrapper)
import { v } from "convex/values";
import { mutation, query } from "./_generated/server";
import { components } from "./_generated/api";
import { getAuthUserId } from "@convex-dev/auth/server";

export const sendNotification = mutation({
  args: { message: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    if (!userId) throw new Error("Not authenticated");

    await ctx.runMutation(components.notifications.lib.send, {
      userId,
      message: args.message,
    });
    return null;
  },
});

export const myUnread = query({
  args: {},
  handler: async (ctx) => {
    const userId = await getAuthUserId(ctx);
    if (!userId) throw new Error("Not authenticated");

    return await ctx.runQuery(components.notifications.lib.listUnread, {
      userId,
    });
  },
});

// Bad: component code cannot rely on app auth or env
const identity = await ctx.auth.getUserIdentity();
const apiKey = process.env.OPENAI_API_KEY;

// Good: the app resolves auth and env, then passes explicit values
const userId = await getAuthUserId(ctx);
if (!userId) throw new Error("Not authenticated");

await ctx.runAction(components.translator.translate, {
  userId,
  apiKey: process.env.OPENAI_API_KEY,
  text: args.text,
});

// Bad: assuming a component function is directly callable by clients
export const send = components.notifications.send;

// Good: re-export through an app mutation or query
export const sendNotification = mutation({
  args: { message: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    if (!userId) throw new Error("Not authenticated");

    await ctx.runMutation(components.notifications.lib.send, {
      userId,
      message: args.message,
    });
    return null;
  },
});

// Bad: parent app table IDs are not valid component validators
args: {
  userId: v.id("users");
}

// Good: treat parent-owned IDs as strings at the boundary
args: {
  userId: v.string();
}

© spokvulcan, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 6 other files (references, assets) in .agents/skills/convex-create-component of spokvulcan/poker-planning.

• SKILL.md
• agents/openai.yaml
• assets/icon.svg
• references/advanced-patterns.md
• references/hybrid-components.md
• references/local-components.md
• references/packaged-components.md

Open the folder on GitHubat commit 665a13f

Used in 8 other repositories

We found 9 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 8 other GitHub owners. This page covers the copy in spokvulcan/poker-planning, which our catalogue first saw on October 7, 2026.

• ajanraj/OpenChat.agents/skills/convex-create-component
• waynesutton/markdown-site.agents/skills/convex-create-component
• openclaw/clawhub.agents/skills/convex-create-component
• vvedantb/eva.agents/skills/convex-create-component
• bholmesdev/hubble.mdpackages/sync-backend/.agents/skills/convex-create-component
• raroque/boop-agent.agents/skills/convex-create-component
• SchroederNathan/amber.agents/skills/convex-create-component.claude/skills/convex-create-component
• aiskillstore/marketplaceskills/get-convex/convex-create-component