convex-explain-app
Skill4 starsChanged 54 days agoMITView on GitHub
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.
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
Read the schema + function surface (functionSpec/source) as the source of truth — never describe behavior the code doesn't show.
- Distinctive: line 28
Read-only: any deployment introspection is read-only (deploy-guard).
≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- GENERATED from convex-agents content/capabilities/explain-app.json — do not edit by hand. -->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/tablesvia 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 — whichv.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).
Trending
Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data
Other versions6 projects use a version of this.
Word for word · 6
- openclaw/clawhub★ 9.5k100% same
- moltbot/molthub★ 9.5k100% same
- clawdbot/clawdhub★ 9.5k100% same
- convex/agent-skills★ 68100% same
- get-convex/agent-skills★ 68100% same
- getsentry/friday★ 0100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Used alongsideProjects with it also use clawhub-content-rights-correspondence, clawhub-convex and 6 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
openclawSkillclawhub-content-rights-correspondence
Use when drafting, sending, or preserving email correspondence for an existing ClawHub content rights case.
Also in 3 projects that use this
- openclawSkill
clawhub-convex
Apply ClawHub-specific Convex conventions and route to the right managed Convex skill. Use for any change under convex/, Convex commands or deployment targeting, query performance, migrations, retention, runtime validation, or skill stat reads and writes in the ClawHub repository.
Also in 3 projects that use this
PostHogSkillwriting-evals
Teaches how to write and run evals on the `products/posthog_ai/eval_harness/` harness — sandboxed agent suites that execute the real coding agent in a Docker or Modal sandbox against a seeded Hedgebox project, and one-shot suites that score a single in-process model invocation per case. Use when adding or changing eval suites, cases, scorers, seeders, or synthesizers under `products/posthog_ai/evals/` or `products/*/evals/`, when touching the harness under `products/posthog_ai/eval_harness/`, or when running or debugging those evals (`hogli evals`). Covers suite kinds and discovery, case anatomy, the seeder/synthesizer split, the one-branch scorer patterns, and how to read results. Not for the LLM Analytics product's evaluation features.
Also in 3 projects that use this
axiomhqSkillaxiom-alerting
Create and manage Axiom monitors and notifiers via the v2 public API. Use when building alerting, routing notifications, validating monitor behavior, and maintaining alert configurations end-to-end.
Also in 3 projects that use this
- +4 more from openclaw
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- codebase-designSkill
- code-reviewSkill
- convex-acquire-domainSkill
- convex-addSkill
- convex-advisorSkill
- convex-agentSkill
- convex-authSkill
- convex-authzSkill
- convex-backupSkill
- convex-billingSkill
- convex-check-updatesSkill
- convex-costSkill
- convex-create-componentSkill
- convex-cronsSkill
- convex-deploy-guardSkill
- convex-designSkill
- convex-docsSkill
- convex-domainsSkill
- convex-envSkill
- convex-expertSkill
- convex-improve-convex-pluginSkill
- convex-insightsSkill
- convex-launch-readinessSkill
- convex-migrate-rehearseSkill
- convex-migrateSkill
- convex-monitorSkill
- convex-optimizeSkill
- convex-quickstartSkill
- convex-reviewerSkill
- convex-seedSkill
- convex-self-healSkill
- convex-sentinelSkill
- convex-shipSkill
- convexSkill
- convex-suggestSkill
- convex-testSkill
- convex-verifySkill
- diagnosing-bugsSkill
- domain-modelingSkill
- grillingSkill
- grill-meSkill
- grill-with-docsSkill
- handoffSkill
- implementSkill
- improve-codebase-architectureSkill
- prototypeSkill
- releaseSkill
- researchSkill
- resolving-merge-conflictsSkill
- setup-afk-codingSkill
- setup-matt-pocock-skillsSkill
- tddSkill
- teachSkill
- to-specSkill
- to-ticketsSkill
- triageSkill
- wayfinderSkill
- writing-for-agentsSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.