How to use the ClawHub Convex Conventions agent skill

What the skill makes the agent do

Agent skills are folders of instructions that an AI agent loads when a task matches the skill's description. This one applies only to ClawHub's repository-specific Convex work. It covers any change under convex/, Convex commands and deployment targeting, query performance, migrations, data retention, runtime validation, and reads and writes of skill statistics.

Before the agent edits Convex code, the skill tells it to read convex/_generated/ai/guidelines.md. Before it runs a Convex command, the skill tells it to name the target runtime as local, dev, or prod, and to say whether the current functions and schema have already been pushed there. The skill then points the agent to the most specific companion skill for the job.

• Query cost, indexes, read amplification, subscriptions, or OCC: convex-performance-audit
• Production migrations, backfills, schema narrowing, or table reshaping: convex-migration-helper and create-and-cleanup-migration
• Tables, TTL fields, cleanup crons, retention, or deprecated table removal: convex-retention
• Auth, reusable components, or setup: the matching managed Convex skill

How to install the clawhub-convex skill

Download the ZIP from this page and unzip it. The skill is a folder that contains SKILL.md and agents/openai.yaml. Put the folder in one of these locations:

• Personal use across projects: ~/.claude/skills/
• One project only: the .claude/skills/ folder inside that project
• In the Claude apps: upload the skill under Settings → Capabilities → Skills

How to trigger the skill with natural requests

You do not need a special command. The agent loads the skill when your request matches its description. Naming the area of work helps. Requests like these match it well: changing a function under convex/, adding an index to speed up a query, planning a backfill migration, or reading and writing a skill's download or star counts.

The skill also works when you ask for a review. Asking the agent to check a Convex change against ClawHub's conventions will lead it to the same rules.

• Add an index for the skills search query and check whether it reads too much data.
• Write a backfill for a new migrated stat field and follow the dual-write pattern.
• Run the Convex function I just changed against dev and tell me which environment you used.
• Review this convex/ diff for ClawHub migration boundaries.

Commands and checks the agent follows

The skill lists the exact Convex commands the agent should use. New or changed functions must be pushed before convex run. For dev, that is bunx convex dev --once. Production goes through the workflow in clawhub-production-release. Committed API and types are regenerated with bunx convex codegen after API or schema changes.

Tests follow the same logic. Mocked ctx tests only cover pure business logic. If behavior depends on pagination, indexes, validators, auth, schedulers, storage, or OCC, the skill asks for a real Convex path as well.

• Import mutations from convex/functions.ts, not convex/_generated/server, so the trigger wrapper runs. Type imports can still come from convex/_generated/server.
• If bunx convex run --env-file .env.local returns 401 MissingAccessToken after login, omit --env-file and use --deployment <name> or --prod.
• Check bunx convex insights --details and bunx convex logs --failure before restructuring a performance-sensitive query.
• Do not disable typechecking for an ordinary direct deploy.

Skill stat fields and migration boundaries

The skills table keeps a compatibility shape for four migrated stats. Each legacy nested field has a top-level source of truth. Read them with readCanonicalStat() from convex/lib/skillStats.ts, which prefers the top-level field and falls back for older documents. Write changes with applySkillStatDeltas(), which updates both shapes in one patch. Any direct patch to these values must update both shapes.

For migrations, the skill defaults to @convex-dev/migrations. Table-wide backfills belong in convex/migrations.ts, and custom or admin-gated repairs belong in convex/maintenance.ts.

• stats.downloads maps to statsDownloads
• stats.stars maps to statsStars
• stats.installsCurrent maps to statsInstallsCurrent
• stats.installsAllTime maps to statsInstallsAllTime
• Nested-only reads remain valid for stats.comments and stats.versions

Safety notes before you use it

The skill does not run scripts itself, but it does use the network, because the Convex commands connect to ClawHub deployments. You need Convex CLI access, and you need to log in for prod or dev targets.

The skill allows direct production deploys with bunx convex deploy -y when a user explicitly asks for one. That can change live data if it is misused. Review production changes yourself and do not let an agent run them unattended. Keep one-off operator migrations out of .github/workflows/deploy.yml.

• Requires Bun, because commands use bunx and bun run.
• Playwright test setup is needed for the bun run test:pw:local-auth step.
• Companion skills must also be installed or the routing will not work.