AgentSkillsCN

convex-core

通过严格的校验器与索引，构建 Convex 的 Schema、查询、变更、动作，以及客户端调用接口。 在数据建模、函数编写、参数与返回值校验，以及性能优化方面，可灵活运用此方法。 当工作涉及 convex/schema.ts 文件、函数定义，或 api.* 引用时，应主动展开相关审计工作。 示例： - 用户：“为多租户应用设计表结构” → 定义 Schema/定义表，并添加索引 - 用户：“编写一个变更操作” → 添加参数与返回值校验器，同时进行认证检查 - 用户：“优化查询” → 添加索引，并使用 withIndex 范围表达式 - 用户：“使用 useQuery” → 展示自动生成的 Hook 使用方式

SKILL.md
--- frontmatter
name: convex-core
description: |-
  Build Convex schemas, queries, mutations, actions, and client usage with strict validators and indexes.
  Use for data modeling, function authoring, argument/return validation, and performance guidance.
  Use proactively when work touches convex/schema.ts, functions, or api.* references.
  
  Examples:
  - user: "Design tables for multi-tenant app" → defineSchema/defineTable with indexes
  - user: "Write a mutation" → args/returns validators + auth checks
  - user: "Optimize query" → add index and withIndex range expression
  - user: "Use useQuery" → show generated hook usage
<overview> Core Convex modeling and function authoring patterns. This skill is the default baseline for Convex work. </overview> <reference> - **Schemas**: https://docs.convex.dev/database/schemas - **Reading data + indexes**: https://docs.convex.dev/database/reading-data/indexes - **Validation**: https://docs.convex.dev/functions/validation - **Functions**: https://docs.convex.dev/functions - **Pagination**: https://docs.convex.dev/database/pagination - **System tables**: https://docs.convex.dev/database/advanced/system-tables </reference> <context name="Core Concepts"> - Schema: `defineSchema`/`defineTable` in `convex/schema.ts`; use `v` validators. - Options: `schemaValidation: false` disables runtime validation; `strictTableNameTypes: false` allows undeclared tables in TS types. - Validation: `args`/`returns` validators for queries/mutations/actions; objects reject extra props; `undefined` is invalid (use `null`). - Discriminated Unions: Use `v.union` and `v.literal` with `as const` for type-safe state/kind definitions. - Types: Use `v.int64()` for 64-bit integers (not `v.bigint()`); `v.null()` for explicit null returns. - IDs: Use `Id<"table">` and `v.id("table")` instead of raw strings. - Records: `v.record(keys, values)` keys MUST be ASCII, non-empty, and NOT start with `_` or `$`. - Validator composition: `Infer`, `.pick`, `.omit`, `.extend`, `.partial` on object validators. </context> <rules>

Schema Rules

  • •You MUST define all tables in convex/schema.ts with defineSchema / defineTable.
  • •System Fields: _id (v.id(tableName)) and _creationTime (v.number()) are added automatically.
  • •You MUST use v.* validators for every field; SHOULD avoid v.any() unless necessary.
  • •Index naming: include all fields in the name, e.g., "by_field1_and_field2". </rules>
  • •Index rules:
    • •You MUST use .index(name, [fields...]).
    • •Field order matters; range expressions MUST follow index order.
    • •Limits: 16 fields per index, 32 indexes per table.

Function Rules

  • •You MUST use new function syntax with args, returns, and handler.
  • •You MUST always validate args and returns (HTTP actions excluded).
  • •Use query for reads, mutation for writes, and action for external/long-running.
  • •Actions MUST NOT access ctx.db; You MUST use ctx.runQuery / ctx.runMutation.
  • •Circular Dependencies: When calling a function in the same file via ctx.run*, You MUST add explicit return type annotations to the receiver variable.

Database Operations

  • •You MUST provide the explicit table name as the first argument to ctx.db.get, ctx.db.patch, ctx.db.replace, and ctx.db.delete.
  • •Replacement: Use ctx.db.replace for full document replacement (throws if missing).
  • •Patching: Use ctx.db.patch for shallow merge updates (throws if missing).
  • •Deletion: Convex queries do NOT support .delete(). You MUST .collect() results and iterate to call ctx.db.delete(id).
  • •Unique: Use .unique() for single document results; it MUST throw if multiple documents match.
  • •You MUST NOT use filter in production queries; use indexes and .withIndex.

TypeScript Best Practices

  • •You MUST use as const for string literals in discriminated unions.
  • •You MUST define arrays as const array: Array<T> = [...] and records as const record: Record<K, V> = {...}.
  • •You MUST prefer Id<"table"> over string for all document identifiers.

Query Performance

  • •You SHOULD prefer .withIndex over .filter on large tables.
  • •If using .withIndex without a range, You MUST pair it with take, first, unique, or paginate.
  • •Search limits: collect() throws if >1024 docs; You SHOULD use take(n), paginate(), or for await iteration for large sets.
  • •Async iteration: Use for await (const row of query) instead of .collect() for streaming large result sets.

Pagination

  • •You MUST use paginationOptsValidator in args.
  • •.paginate() returns { page, isDone, continueCursor }.
  • •Pages are reactive; size MAY change.
  • •You SHOULD avoid strict returns validators for the full .paginate() result object; validate page or use v.any().

Client Patterns

  • •You MUST use api.* references from convex/_generated/api.
  • •React hooks: useQuery, useMutation, useAction, usePaginatedQuery.
  • •You MUST NOT call mutations or actions during render.

Safety

  • •You MUST enforce auth per function; check identity via ctx.auth helpers.
  • •You MUST NOT expose sensitive logic in public functions; MUST use internal ones.
</rules>