convex-explain-app

Original：🇺🇸 English

Translated

Explain an existing Convex app — data model + relationships, public vs internal functions, auth/ownership model, components, a request→data flow — read from the schema and function surface. Read-only.

252installs

Sourceget-convex/agent-skills

Added on2026-08-02

NPX Install

npx skill4agent add get-convex/agent-skills convex-explain-app

SKILL.md Content

View Translation Comparison →

Explain this Convex app

Before you can safely change an app you have to know what it is — and reading 15 function files top-to-bottom is slow and error-prone. This capability produces the map fast and accurately by reading the two sources that can't lie: the schema (the data model) and the function surface (

functionSpec

/ the exported queries/mutations/actions). It is deliberately DESCRIPTIVE — it explains what IS, hands judgment to the audit capabilities and changes to the fixers. It is also the natural first step of an optimize or self-heal session, and the reusable 're-explain the current architecture' that 'change what you built' depends on.

Workflow

DETECT the app: the
```
convex/
```
directory,
```
schema.ts
```
, and whether a deployment exists (if one does,
```
functionSpec
```
/
```
tables
```
via the official MCP give the authoritative live surface; if not, read the source directly). deploy-guard classifies any deployment read as read-only.
DATA MODEL: from
```
schema.ts
```
, list every table with its fields and, crucially, its RELATIONSHIPS — which
```
v.id("other")
```
fields point where, and which indexes exist (indexes reveal the intended access paths). Draw the foreign-key graph in words: 'tasks belong to projects (projectId) and users (ownerId); messages belong to conversations'.
FUNCTION SURFACE: enumerate every exported function, split PUBLIC (query/mutation/action — the attack/API surface) from INTERNAL (internalQuery/... — not client-reachable), and for each give a one-line 'what it does + what it touches'. The public/internal split is the single most important thing a newcomer needs and the thing source-skimming most often gets wrong.
AUTH / OWNERSHIP MODEL: state how identity is established (auth.config.ts provider? a users table keyed by tokenIdentifier?) and how ownership is enforced (is there a requireOwner-style check? which field is the owner?). Say plainly if there is NO auth foundation — that is load-bearing context for anyone about to change the app. (Describe the model; do not audit it for holes — that's convex-authz.)
COMPONENTS + EXTERNAL EDGES: list the
```
@convex-dev/*
```
components installed (convex.config.ts) and what they provide, the HTTP routes (http.ts) and crons, and any external calls in actions (which APIs, which env vars).
FLOW: trace 1-2 representative end-to-end paths ('client calls createTask → validates → inserts into tasks scoped to the caller → listMyTasks reads it back by the by_owner index') so the reader sees the moving parts connected, not just catalogued.
PRESENT as a scannable map (data model → public/internal functions → auth model → components/edges → a flow or two), accurate to the source. End by pointing at the next verbs: convex-reviewer/convex-authz to audit it, launch-readiness to score it, design/convex-expert to extend it. Never invent behavior the source doesn't show; if something is ambiguous, say so rather than guessing.

Rules

Read the schema + function surface (functionSpec/source) as the source of truth — never describe behavior the code doesn't show; flag ambiguity instead of guessing.
Lead with the two things a newcomer most needs and skimming most often gets wrong: the data-model relationship graph and the public-vs-internal function split.
State the auth/ownership model plainly, including 'there is no auth foundation' when that's the case — but DESCRIBE it; auditing it for holes is convex-authz's job.
Descriptive, not evaluative: explain-app maps what IS and hands judgment to the audit capabilities and changes to the fixers.
Read-only: any deployment introspection is read-only (deploy-guard); the app is not modified.
End by pointing at the right next verb (audit → reviewer/authz, score → launch-readiness, extend → design/expert).