Guide · Agent skill
How to use the Explain a Convex App agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The convex-explain-app skill is an agent skill for Claude that reads an existing Convex app and produces a structured map of it: the data model, the public and internal functions, how users and ownership are identified, and the external services and components in use. It is written for developers onboarding onto an unfamiliar Convex codebase or planning changes to one. After this guide you will know how to install the skill, ask for an explanation in plain language, and read the map it returns.
Explain a Convex Appopenclaw/clawhub · MIT Download the skill Quick start
- 1Download the ZIP. Download the convex-explain-app skill ZIP from this page. It contains SKILL.md.
- 2Install it. Unzip it into ~/.claude/skills/ for personal use or into your project's .claude/skills/ folder, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Confirm your project is Convex. Make sure the project has a convex/ directory and a schema.ts file.
- 4Ask in plain language. Request an explanation of the app, such as mapping the data model or listing public functions.
- 5Read the map. Review the data model, the public and internal function split, the auth model and the request flows, then use the pointed-to skills for audits or changes.
What the skill makes the agent do
An agent skill is a folder containing a SKILL.md file with instructions that the agent loads when a request matches the skill's description. This one, named convex-explain-app, tells the agent to explain an existing Convex app by reading its schema and function surface instead of reading every file top to bottom.
The skill is descriptive and read-only. It explains what the app currently is and does not change it. When you want an audit or a change, the skill points you to other skills.
- Lists every database table with its fields and relationships, including which fields reference other tables and which indexes exist.
- Splits exported functions into public (query, mutation, action) and internal (internalQuery and similar), with a one-line note on what each does.
- Describes how identity is established and how ownership is enforced, and says plainly if there is no auth foundation.
- Lists installed @convex-dev components, HTTP routes, crons and external calls made from actions.
- Traces one or two example request paths from client call through validation and data access.
Install the skill in Claude
Download the skill ZIP from this page. The package contains one file, SKILL.md. You can install it for yourself across all projects or for a single project.
For a personal install, unzip the file into ~/.claude/skills/. For a project-only install, unzip it into the project's .claude/skills/ folder. In the Claude apps, you can also upload the ZIP under Settings, then Capabilities, then Skills.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check that your project qualifies
The skill is built for Convex projects. The source says it needs a Convex project with a convex/ directory and a schema.ts file. Without them, the agent has nothing to map.
A live deployment is optional. If you have one and the official Convex MCP is available, the skill can use it for live introspection of the function surface. If not, it reads the source files directly. Any deployment read is treated as read-only.
- Required: a convex/ directory and schema.ts
- Optional: an existing Convex deployment
- Optional: the official Convex MCP for live introspection
Ask for an explanation with natural requests
You do not need a special command. Describe what you want in plain language that matches the skill's purpose. Phrases such as explain this Convex app, map the data model, or which functions are public tend to match the skill's description. The skill's exact trigger behavior is not spelled out in its source, so if the agent does not pick it up, name the skill directly.
Ask for a specific slice when the app is large. Requests like how does a new task get saved, or which tables reference users, give a focused answer.
- Explain this Convex app and give me a map of it.
- Which Convex functions can a client call directly, and which are internal?
- How do users and ownership work in this app?
- Walk me through what happens when the client creates a task.
- What external services does this app call from its actions?
Read the map and know what it does not cover
The output is organized as a data model, then public and internal functions, then the auth model, then components and external edges, and finally one or two request flows. The skill is designed to put the relationship graph and the public-versus-internal split first, since those are the parts newcomers most often misread.
The skill does not find security holes or bugs. It describes the app. For auditing, the source points to convex-reviewer and convex-authz. To score launch readiness, it points to launch-readiness. To extend the app, it points to design or convex-expert. If something in the code is ambiguous, the skill is meant to say so rather than guess.
- Audit or review: convex-reviewer or convex-authz
- Launch readiness score: launch-readiness
- Extend the app: design or convex-expert
What people use it for
- Onboarding onto an inherited Convex codebase by getting a data model and function map before touching code.
- Getting a quick architecture overview before planning a feature that adds tables or functions.
- Preparing for a security or launch-readiness review by first understanding which functions are client-reachable and how ownership is checked.
- Tracing how a request moves from a client call through the code to the tables it reads and writes.
Frequently asked questions
Is the convex-explain-app skill free to use?
The skill is published under the MIT licence, as listed on this page. The source does not mention pricing for anything else, so check the licence file in the package for the full terms.
What do I need to run the convex-explain-app skill?
You need a Convex project with a convex/ directory and a schema.ts file. A live Convex deployment and the official Convex MCP are optional and only add live introspection of the function surface.
Does this skill find bugs or security holes in my Convex app?
No. It is designed to describe what the app is, not to audit it. For reviews, the source points to convex-reviewer and convex-authz, and for a readiness score it points to launch-readiness.
Does the skill change my code?
No. The skill is read-only and descriptive, so it explains the app without modifying it. Changes are handed to other skills.
Does it work with non-Convex backends?
No. It targets Convex schema and function conventions, so it is not suited to other backends.
What if my app's source code is not available?
The skill relies on reading the schema and function code, so it is not suited to apps whose source you cannot access. If you have a deployment and the official Convex MCP, the skill can use live introspection, but the source describes that as optional.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are onboarding onto a Convex app, need a fast architecture map before making changes, or are preparing for a review and want to understand the app first. Pick a different skill if you need security findings or bug detection, which this skill explicitly does not do, or if your backend is not Convex.
Download the skill