{"id":"364a04c5-4ea3-4bbf-9469-29ed349a7fa3","shortId":"Xzwj3w","kind":"skill","title":"convex-backend","tagline":"Convex backend development guidelines. Use when writing Convex functions, schemas, queries, mutations, actions, or any backend code in a Convex project. Triggers on tasks involving Convex database operations, real-time subscriptions, file storage, or serverless functions.","description":"# Convex Backend Guidelines\n\n### When to Load\n\n- **Trigger**: Convex-specific development, writing Convex functions, schemas, queries, mutations, actions, or real-time subscriptions\n- **Skip**: Project does not use Convex as its backend\n\nComprehensive guide for building Convex backends with TypeScript. Covers function syntax, validators, schemas, queries, mutations, actions, scheduling, and file storage.\n\n## When to Apply\n\nReference these guidelines when:\n\n- Writing new Convex functions (queries, mutations, actions)\n- Defining database schemas and validators\n- Implementing real-time data fetching\n- Setting up cron jobs or scheduled functions\n- Working with file storage\n- Designing API structure\n\n## Rule Categories\n\n| Category          | Impact   | Description                                   |\n| ----------------- | -------- | --------------------------------------------- |\n| Function Syntax   | CRITICAL | New function syntax with args/returns/handler |\n| Validators        | CRITICAL | Type-safe argument and return validation      |\n| Schema Design     | HIGH     | Table definitions, indexes, system fields     |\n| Query Patterns    | HIGH     | Efficient data fetching with indexes          |\n| Mutation Patterns | MEDIUM   | Database writes, patch vs replace             |\n| Action Patterns   | MEDIUM   | External API calls, Node.js runtime           |\n| Scheduling        | MEDIUM   | Crons and delayed function execution          |\n| File Storage      | LOW      | Blob storage and metadata                     |\n\n## Quick Reference\n\n### Function Registration\n\n```typescript\n// Public functions (exposed to clients)\nimport { query, mutation, action } from \"./_generated/server\";\n\n// Internal functions (only callable from other Convex functions)\nimport {\n  internalQuery,\n  internalMutation,\n  internalAction,\n} from \"./_generated/server\";\n```\n\n### Function Syntax (Always Use This)\n\n```typescript\nexport const myFunction = query({\n  args: { name: v.string() },\n  returns: v.string(),\n  handler: async (ctx, args) => {\n    return \"Hello \" + args.name;\n  },\n});\n```\n\n### Common Validators\n\n| Type     | Validator                         | Example       |\n| -------- | --------------------------------- | ------------- |\n| String   | `v.string()`                      | `\"hello\"`     |\n| Number   | `v.number()`                      | `3.14`        |\n| Boolean  | `v.boolean()`                     | `true`        |\n| ID       | `v.id(\"tableName\")`               | `doc._id`     |\n| Array    | `v.array(v.string())`             | `[\"a\", \"b\"]`  |\n| Object   | `v.object({...})`                 | `{name: \"x\"}` |\n| Optional | `v.optional(v.string())`          | `undefined`   |\n| Union    | `v.union(v.string(), v.number())` | `\"x\"` or `1`  |\n| Literal  | `v.literal(\"status\")`             | `\"status\"`    |\n| Null     | `v.null()`                        | `null`        |\n\n### Function References\n\n```typescript\n// Public functions\nimport { api } from \"./_generated/api\";\napi.example.myQuery; // convex/example.ts → myQuery\n\n// Internal functions\nimport { internal } from \"./_generated/api\";\ninternal.example.myInternalMutation;\n```\n\n### Query with Index\n\n```typescript\n// Schema\nmessages: defineTable({...}).index(\"by_channel\", [\"channelId\"])\n\n// Query\nawait ctx.db\n  .query(\"messages\")\n  .withIndex(\"by_channel\", (q) => q.eq(\"channelId\", channelId))\n  .order(\"desc\")\n  .take(10);\n```\n\n### Key Rules\n\n1. **Always include `args` and `returns` validators** on all functions\n2. **Use `v.null()` for void returns** - never omit return validator\n3. **Use `withIndex()` not `filter()`** - define indexes in schema\n4. **Use `internalQuery/Mutation/Action`** for private functions\n5. **Actions cannot access `ctx.db`** - use runQuery/runMutation instead\n6. **Include type annotations** when calling functions in same file\n\n## Full Compiled Document\n\nFor the complete guide with all rules and detailed code examples, see: `AGENTS.md`","tags":["convex","backend","claude","workflow","cloudai-x","agent-skills","ai-agents","claude-code","codex","cursor","skills"],"capabilities":["skill","source-cloudai-x","skill-convex-backend","topic-agent-skills","topic-ai-agents","topic-claude-code","topic-codex","topic-cursor","topic-skills","topic-workflow"],"categories":["claude-workflow-v2"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/CloudAI-X/claude-workflow-v2/convex-backend","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add CloudAI-X/claude-workflow-v2","source_repo":"https://github.com/CloudAI-X/claude-workflow-v2","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 1352 github stars · SKILL.md body (3,944 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-03T00:52:55.514Z","embedding":null,"createdAt":"2026-04-18T21:54:51.767Z","updatedAt":"2026-05-03T00:52:55.514Z","lastSeenAt":"2026-05-03T00:52:55.514Z","tsv":"'/_generated/api':305,314 '/_generated/server':215,229 '1':289,345 '10':342 '2':355 '3':365 '3.14':262 '4':374 '5':380 '6':388 'access':383 'action':16,58,88,106,178,213,381 'agents.md':413 'alway':232,346 'annot':391 'api':130,182,303 'api.example.myquery':306 'appli':95 'arg':240,248,348 'args.name':251 'args/returns/handler':144 'argument':150 'array':270 'async':246 'await':328 'b':274 'backend':3,5,19,42,72,78 'blob':196 'boolean':263 'build':76 'call':183,393 'callabl':219 'cannot':382 'categori':133,134 'channel':325,334 'channelid':326,337,338 'client':209 'code':20,410 'common':252 'compil':399 'complet':403 'comprehens':73 'const':237 'convex':2,4,11,23,29,41,49,53,69,77,102,222 'convex-backend':1 'convex-specif':48 'convex/example.ts':307 'cover':81 'critic':139,146 'cron':120,188 'ctx':247 'ctx.db':329,384 'data':116,166 'databas':30,108,173 'defin':107,370 'definet':322 'definit':158 'delay':190 'desc':340 'descript':136 'design':129,155 'detail':409 'develop':6,51 'doc._id':269 'document':400 'effici':165 'exampl':256,411 'execut':192 'export':236 'expos':207 'extern':181 'fetch':117,167 'field':161 'file':36,91,127,193,397 'filter':369 'full':398 'function':12,40,54,82,103,124,137,141,191,202,206,217,223,230,297,301,310,354,379,394 'guid':74,404 'guidelin':7,43,98 'handler':245 'hello':250,259 'high':156,164 'id':266 'impact':135 'implement':112 'import':210,224,302,311 'includ':347,389 'index':159,169,318,323,371 'instead':387 'intern':216,309,312 'internal.example.myinternalmutation':315 'internalact':227 'internalmut':226 'internalqueri':225 'internalquery/mutation/action':376 'involv':28 'job':121 'key':343 'liter':290 'load':46 'low':195 'medium':172,180,187 'messag':321,331 'metadata':199 'mutat':15,57,87,105,170,212 'myfunct':238 'myqueri':308 'name':241,277 'never':361 'new':101,140 'node.js':184 'null':294,296 'number':260 'object':275 'omit':362 'oper':31 'option':279 'order':339 'patch':175 'pattern':163,171,179 'privat':378 'project':24,65 'public':205,300 'q':335 'q.eq':336 'queri':14,56,86,104,162,211,239,316,327,330 'quick':200 'real':33,61,114 'real-tim':32,60,113 'refer':96,201,298 'registr':203 'replac':177 'return':152,243,249,350,360,363 'rule':132,344,407 'runquery/runmutation':386 'runtim':185 'safe':149 'schedul':89,123,186 'schema':13,55,85,109,154,320,373 'see':412 'serverless':39 'set':118 'skill' 'skill-convex-backend' 'skip':64 'source-cloudai-x' 'specif':50 'status':292,293 'storag':37,92,128,194,197 'string':257 'structur':131 'subscript':35,63 'syntax':83,138,142,231 'system':160 'tabl':157 'tablenam':268 'take':341 'task':27 'time':34,62,115 'topic-agent-skills' 'topic-ai-agents' 'topic-claude-code' 'topic-codex' 'topic-cursor' 'topic-skills' 'topic-workflow' 'trigger':25,47 'true':265 'type':148,254,390 'type-saf':147 'typescript':80,204,235,299,319 'undefin':282 'union':283 'use':8,68,233,356,366,375,385 'v.array':271 'v.boolean':264 'v.id':267 'v.literal':291 'v.null':295,357 'v.number':261,286 'v.object':276 'v.optional':280 'v.string':242,244,258,272,281,285 'v.union':284 'valid':84,111,145,153,253,255,351,364 'void':359 'vs':176 'withindex':332,367 'work':125 'write':10,52,100,174 'x':278,287","prices":[{"id":"db291d97-2781-401a-b9ee-717090fd0529","listingId":"364a04c5-4ea3-4bbf-9469-29ed349a7fa3","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"CloudAI-X","category":"claude-workflow-v2","install_from":"skills.sh"},"createdAt":"2026-04-18T21:54:51.767Z"}],"sources":[{"listingId":"364a04c5-4ea3-4bbf-9469-29ed349a7fa3","source":"github","sourceId":"CloudAI-X/claude-workflow-v2/convex-backend","sourceUrl":"https://github.com/CloudAI-X/claude-workflow-v2/tree/main/skills/convex-backend","isPrimary":false,"firstSeenAt":"2026-04-18T21:54:51.767Z","lastSeenAt":"2026-05-03T00:52:55.514Z"}],"details":{"listingId":"364a04c5-4ea3-4bbf-9469-29ed349a7fa3","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"CloudAI-X","slug":"convex-backend","github":{"repo":"CloudAI-X/claude-workflow-v2","stars":1352,"topics":["agent-skills","ai","ai-agents","claude-code","codex","cursor","skills","workflow"],"license":"mit","html_url":"https://github.com/CloudAI-X/claude-workflow-v2","pushed_at":"2026-02-14T18:09:29Z","description":"Universal Claude Code workflow plugin with agents, skills, hooks, and commands","skill_md_sha":"63ca96d614fe57cb81175a2be7a38f14c8cec1ea","skill_md_path":"skills/convex-backend/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/CloudAI-X/claude-workflow-v2/tree/main/skills/convex-backend"},"layout":"multi","source":"github","category":"claude-workflow-v2","frontmatter":{"name":"convex-backend","description":"Convex backend development guidelines. Use when writing Convex functions, schemas, queries, mutations, actions, or any backend code in a Convex project. Triggers on tasks involving Convex database operations, real-time subscriptions, file storage, or serverless functions."},"skills_sh_url":"https://skills.sh/CloudAI-X/claude-workflow-v2/convex-backend"},"updatedAt":"2026-05-03T00:52:55.514Z"}}