# Convex Explain App

> Explica una app Convex existente — modelo de datos y relaciones, funciones públicas vs internas, modelo de auth/ownership, componentes y un flujo petición→datos. Solo lectura.

Fuente: https://skillsagentes.com/skills/get-convex/agent-skills/convex-explain-app
Markdown: https://skillsagentes.com/skills/get-convex/agent-skills/convex-explain-app.md

Repositorio: https://github.com/get-convex/agent-skills
Autor: get-convex
Licencia: Apache-2.0
Actualizado: el mes pasado
Coste de contexto: 52 tok instalada, 1k tok al activarse, 1k tok con todos los archivos del bundle
Bundle: 1 archivo, 4 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add get-convex/agent-skills --skill convex-explain-app --agent claude-code
# Cursor
npx -y skills add get-convex/agent-skills --skill convex-explain-app --agent cursor
# Codex
npx -y skills add get-convex/agent-skills --skill convex-explain-app --agent codex
# Gemini CLI
npx -y skills add get-convex/agent-skills --skill convex-explain-app --agent gemini
# Windsurf
npx -y skills add get-convex/agent-skills --skill convex-explain-app --agent windsurf
# Cline
npx -y skills add get-convex/agent-skills --skill convex-explain-app --agent cline
```

## Qué hace

- Lee schema.ts y el function surface (functionSpec) para mapear tablas y relaciones
- Separa funciones públicas (query/mutation/action) de internas (internalQuery/...)
- Describe el modelo de auth/ownership y si no existe fundamento de auth
- Lista componentes @convex-dev/*, rutas HTTP, crons y llamadas externas
- Traza 1-2 flujos end-to-end representativos de petición→datos

## Cuándo usarla

- Antes de cambiar una app Convex y necesitas entender qué es primero
- Como primer paso natural de una sesión de optimize o self-heal
- Para re-explicar la arquitectura actual antes de modificarla

## Cuándo no

- Cuando lo que se necesita es auditar el código en busca de fallos (usa convex-reviewer/convex-authz)
- Cuando se necesita puntuar el launch-readiness o extender la app (usa design/convex-expert)

## Qué la activa

- "Explícame cómo está construida esta app de Convex"
- "Mapea el modelo de datos y las funciones públicas vs internas de este proyecto Convex"
- "¿Cómo funciona el modelo de auth y ownership en esta app?"

## Antes de instalar

- Requiere un directorio convex/ con schema.ts, y opcionalmente un deployment (usando el MCP oficial para functionSpec/tables en modo solo lectura).

## Archivos

- SKILL.md — 4 KB

## SKILL.md

Reproducido tal cual desde get-convex/agent-skills bajo Apache-2.0. Esta sección es el documento original y está en inglés.

<!-- 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

1. 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.
2. 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'.
3. 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.
4. 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.)
5. 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).
6. 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.
7. 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).

## Dónde encaja

- Categoría: [Documentos](https://skillsagentes.com/categorias/documentos.md) — Lee, escribe y transforma archivos PDF, DOCX, XLSX y PPTX.
- Creador: [get-convex](https://skillsagentes.com/creators/get-convex.md) — 33 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Convex Quickstart](https://skillsagentes.com/skills/get-convex/agent-skills/convex-quickstart.md): Levanta un template Next.js + Convex barebones a partir de una idea en una frase.
- [Convex Authz](https://skillsagentes.com/skills/get-convex/agent-skills/convex-authz.md): Audita y refuerza la autorización de una app Convex: impersonación por identity-from-arg, checks de ownership por documento faltantes, queries públicas que filtran datos por un id del cliente y escrituras en un contenedor ajeno.
- [Convex Design](https://skillsagentes.com/skills/get-convex/agent-skills/convex-design.md): Diseña y construye backends reactivos y type-safe de nivel producción en Convex: schema, queries/mutations/actions, índices, auth, storage, scheduling, multiplayer en tiempo real y workflows LLM/agentes.
- [Convex Expert](https://skillsagentes.com/skills/get-convex/agent-skills/convex-expert.md): Especialista en el backend de Convex: código dentro de convex/ (funciones, schemas, índices, queries, mutations, actions, endpoints HTTP, cron jobs, storage, auth y componentes).
- [Convex Agent](https://skillsagentes.com/skills/get-convex/agent-skills/convex-agent.md): Añade un backend de agente de IA / RAG (@convex-dev/agent) a la app Convex.

## Skills relacionadas

- [Pdf](https://skillsagentes.com/skills/anthropics/skills/pdf.md): Úsalo siempre que quieras hacer algo con archivos PDF: leer o extraer texto y tablas, combinar, dividir, rotar, poner marcas de agua, crear, rellenar formularios, cifrar o hacer OCR de escaneados.
- [Update Docs](https://skillsagentes.com/skills/vercel/next.js/update-docs.md): Flujo guiado para actualizar la documentación de Next.js según los cambios de código. Úsalo al preguntar qué documentación hace falta, sincronizar docs con código o documentar una funcionalidad.
- [Write Api Reference](https://skillsagentes.com/skills/vercel/next.js/write-api-reference.md): Produce documentación de referencia de API de Next.js — funciones, componentes, convenciones de archivo, directivas y opciones de configuración — como página .mdx con frontmatter, ejemplos y reglas.
- [Document Generate](https://skillsagentes.com/skills/garrytan/gstack/document-generate.md): Genera documentación completa desde cero para una feature, módulo o proyecto entero, siguiendo el framework Diataxis. (gstack)
- [Ppt Generation](https://skillsagentes.com/skills/bytedance/deer-flow/ppt-generation.md): Se usa cuando el usuario pide generar, crear o hacer presentaciones (PPT/PPTX). Crea diapositivas visualmente ricas generando una imagen por diapositiva y componiéndolas en un archivo PowerPoint.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)