Convex Insights skill for Claude Code: ask your Convex logs and health questions

Makes Claude answer questions about your running Convex app from its logs and health data, with evidence and a dashboard link.

Installs: 38.4K; on skills.sh
Stars: 68; on GitHub
Updated: Oct 2026; last repo commit

Ask what is failing, what broke after a deploy, or why one call failed. Claude names the deployment first, looks up real function names, then picks one of three views: failures, health or a single-request trace. It fetches a bounded window of recent logs and filters it itself, because SKILL.md says the logs tool has no server-side filter for status, function, request ID or time.

The answer is a one-line finding, the evidence with counts and one example, and when possible a link to the dashboard that Claude builds itself. SKILL.md says an insights pass runs no mutation. Performance and cost fixes go to convex-advisor. The skill folder holds one file, SKILL.md.

Good for

Convex developers debugging failures or a bad deploy
Teams asking "what is erroring right now" about a live app
Anyone who wants log answers without reading raw output

Install convex-insights

Claude Code

Copy this prompt.

Install the convex-insights skill in Claude Code. Run this command:

npx skills add https://github.com/convex/agent-skills --skill convex-insights --skill convex-deploy-guard

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

SKILL.md runs convex-deploy-guard steps 0 and 1 first, so the first command installs it too. It hands findings to convex-advisor, convex-reviewer, convex-authz, convex-monitor, convex-sentinel as optional hand-offs; install those separately if you want them. Convex's docs say the skills CLI installs skills into .agents/skills/ in your project. The "All Convex skills" command installs every skill in the repo, which has 33 skill folders. One of them, convex-improve-convex-plugin, is listed in the Convex docs as sending your coding session's transcript to the Convex team. Run this skill with /convex-insights in Claude Code or $convex-insights in Codex, or let the agent pick it when the task fits. This skill reads your deployment through the official Convex MCP server, which is not part of the skills. Add the server command to your client's MCP settings; the Convex docs also describe an official plugin that starts it for you.

Built from the package data we hold. Not yet tested by us.

What's in the skill

When it loads

Query a running Convex app's logs + health in natural language (official MCP): failures, slow/expensive functions, deploy causality — scoped, evidence-backed, with a dashboard deep link.

Sections in SKILL.md

Workflow
Rules

Key facts

Author: Convex (the vendor's own repo; Convex's docs list it among the skills it provides)
Repo: convex/agent-skills
License: Apache-2.0 (LICENSE file; the README says original content is Apache-2.0)
Installs on skills.sh: 38,371 (Nov 2, 2026)
GitHub stars: 68 (Nov 2, 2026)
Last commit to the repo: Oct 29, 2026
What installs: 1 file: SKILL.md
Needs: The official Convex MCP server (logs, insights, functionSpec, status tools)
Works in: Claude Code, Cursor, VS Code with GitHub Copilot, Windsurf, Codex (README lists how to invoke skills in each)
skills.sh audits: Gen Agent Trust Hub: pass, Socket: pass, Snyk: warn

What it includes

Names the deployment before it reads logs or insights
Follows convex-deploy-guard steps 0 and 1. Reading is read-only, and prod mutation flags stay off.
Read · Guard the target
Lists real function names with functionSpec and the version with status
Claude never guesses identifiers, so a name your app does not have does not give a confusing empty result.
Network · Discover first
Fetches recent logs and groups failures by function and error message
It returns counts and the first stack for each group. It answers questions like what is erroring or what failed after a deploy.
Network · Failures view
Shows the 72-hour read-limit and write-conflict events, ranked
Cloud only. It hands root-causing and fixes to convex-advisor as pointers.
Network · Health view
Filters recent logs to one request ID or function to read the full run
It answers why one specific call failed.
Network · Trace view
Compares when a failure started with the deployment version from status
Used when you ask whether your deploy broke something. SKILL.md says to correlate the log timestamps with the version, not to assert a cause.
Network · Deploy causality
Gives the finding, the evidence and a dashboard.convex.dev link when possible
SKILL.md says no tool returns the link, so Claude builds it from the deployment name and function.
Answer with a link

From the official docs

Permissions

Medium risk

Claude reads your logs and health data through the Convex MCP, and logs can contain personal data that then enters the conversation. Point it at a dev deployment unless you need production, and keep the prod-change flag off.

What it can do

Read your data
Create and change things
Delete things
Read-only modeHow to turn it on

Watch out for

Logs can contain personal data
The Convex MCP docs call logs a PII read operation, off for production by default. Lines Claude reads enter the chat, so use dev when you can. docs.convex.dev
Dashboard links are built by Claude
SKILL.md says no tool returns a link, so Claude composes one from the deployment name and function. Check it opens the right view. github.com
Answers come from a recent window only
SKILL.md fetches a bounded count of recent log entries and filters locally, so older failures may not appear. github.com
Log queries are written as CLI-style commands
SKILL.md writes them as logs --history <n> --jsonl, with --prod and --deployment flags. The Convex MCP docs describe the logs tool as similar to npx convex logs, and say npx convex commands an agent runs use the full authorization of your credentials unless you use a scoped deploy key. docs.convex.dev

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	SKILL.md says an insights pass runs no mutation. Our advice: start the MCP with the run and env tools disabled (--disable-tools) to enforce it.
Talks to	Your Convex deployment, through the Convex MCP
Scopes	Reads recent logs, insights, function specs and deployment status through the Convex MCP

Questions

How do I install convex-insights?

Use the install box above, and add the Convex MCP server to your client too, since the skill reads logs and insights through it. The first command also installs convex-deploy-guard, which SKILL.md runs first to name the deployment. SKILL.md hands findings to convex-advisor, convex-reviewer, convex-authz, monitor and sentinel; those are optional and install separately. Run the skill with /convex-insights in Claude Code or $convex-insights in Codex.

Why does it fetch logs and filter them itself?

SKILL.md says logs takes only --history <n> (a count, not a time window), --success, --jsonl, --prod and --deployment, with no status, function, request ID or time filter. It says insights has no function filter either. So Claude fetches a bounded recent window and filters it locally.

Can it see personal data in my logs?

Logs can contain it. The Convex MCP docs list logs as a PII read operation that is off for production by default and needs --cautiously-allow-production-pii. Log lines Claude reads become part of the conversation, so use a dev deployment when you can.

Are the dashboard links reliable?

SKILL.md says no tool returns a dashboard link, so Claude builds one from the deployment name and function. Our advice: click through to confirm it opens the right view before you rely on it.

Is it safe?

It reads logs and health data through the Convex MCP, and SKILL.md says it never runs a mutation or enables prod mutation flags. Logs can hold personal data that then enters the chat. Our advice: point it at a dev deployment unless you need prod.

Is it official?

Yes. It is in Convex's own agent-skills repo, and Convex's docs list it among the agent skills Convex provides.

Does it work in the Claude app?

The README and Convex docs name Claude Code, Cursor, VS Code with GitHub Copilot, Windsurf and Codex. They do not name the Claude app, and this skill works on a local project, so we list no Claude app install.

Information

updated Nov 2, 2026

Repository: convex/agent-skills
Folder: skills/convex-insights

convex/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

convex/agent-skills README · github.com
Convex docs: Agent Skills · docs.convex.dev
Convex docs: MCP server · docs.convex.dev
convex-insights SKILL.md · github.com
convex-advisor SKILL.md · github.com
npx convex mcp reference · docs.convex.dev