SKILL.md
Convex functions
Every exported function in convex/ uses the object form with args and returns validators. Pick the type by what the handler touches: queries read, mutations write, actions call out.
Pick the function type
| Type | Database | External calls | Callable by | Use for |
|---|---|---|---|---|
query |
Read | No | Clients, other functions | Reads. Cached and reactive. |
mutation |
Read and write | No | Clients, other functions | Writes. One transaction. |
action |
Only via runQuery and runMutation |
Yes | Clients, scheduler, other actions | fetch, third party SDKs, Node APIs |
internalQuery, internalMutation, internalAction |
Same as the public form | Same | Only other Convex functions | Scheduled work, crons, privileged writes |
httpAction |
Only via runQuery and runMutation |
Yes | HTTP requests in convex/http.ts |
Webhooks, REST endpoints |
Default to query or mutation. Reach for an action only when the handler must talk to something outside Convex.
The object form
Declare args and returns on every function. A function that returns nothing declares returns: v.null() and returns null. Hoist a shared document validator when several functions return the same shape.