How to use the Convex Retention Rules agent skill

What an agent skill is and what this one makes the agent do

An agent skill is a file of instructions that an AI coding agent reads when a task matches the skill's description. This one is a single file, SKILL.md, and it is written for maintainers of the ClawHub codebase.

Once loaded, the skill directs the agent to classify every current Convex table in convex/lib/retentionPolicy.ts. Ephemeral tables need an indexed, bounded cleanup path unless their lifecycle is handled by usage-time validation or a documented component. The agent is also told to avoid bulk-clearing active auth state and to run specific tests and checks after changes.

• Add every new schema table to RETENTION_POLICIES, which the Record<TableNames, RetentionPolicy> type enforces.
• Prune ephemeral tables with .withIndex() and .take(...) rather than unbounded deletes.
• Use RETENTION_STANDARD_BATCH_SIZE for ordinary retention jobs.
• Keep cron jobs pointed at bounded cleanup entrypoints only.
• Expired authSessions and authRefreshTokens are pruned by convex/retention.ts.

Install the convex-retention skill

Download the ZIP from this page. Unzip it into ~/.claude/skills/ to make it available across your projects, or into a project's .claude/skills/ folder to limit it to that project.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/.
• Project install: unzip into the project's .claude/skills/ folder.
• Claude apps: Settings → Capabilities → Skills, then upload.

Check the requirements before you rely on it

The skill assumes a ClawHub-style Convex setup. It expects the clawhub-convex skill to be present and the file convex/_generated/ai/guidelines.md to exist, because the agent is told to read both first. It also uses Bun to run bunx convex commands and Vitest for tests.

It references project files such as convex/lib/retentionPolicy.ts and other skills, including convex-migration-helper. If those do not exist in your repository, the skill's instructions will not map onto your code.

• Convex project with the clawhub-convex skill and convex/_generated/ai/guidelines.md
• Bun, for bunx convex commands
• Vitest, for focused tests

Trigger the skill with natural requests

The skill loads when your request matches its description. Describe the retention-related change in plain terms and name the kind of work involved. The description covers adding or changing ClawHub Convex tables, TTL fields, cleanup crons, retention policy, auth or session cleanup, metric dedupe cleanup, and deprecated table removal.

Requests that fit the description are more likely to load the skill. A request about an unrelated part of the app probably will not.

• Add a new Convex table for password reset tokens with a TTL field and a cleanup cron.
• Change the expiration on the existing session-related table and update its cleanup.
• Remove a deprecated Convex table and make sure it is classified in the retention policy.
• Add dedupe cleanup for metric events that stops old rows from piling up.

Run the verification steps the skill expects

The skill ends with a verification list. Add or update focused tests for policy classification and cleanup behavior. Run the focused Vitest slice for the cleanup modules you touched. After schema or API changes, run codegen. Then run a real Convex runtime check.

• Write or update focused tests for policy classification and cleanup behavior.
• Run the focused Vitest slice for touched cleanup modules.
• Run codegen after schema or API changes.
• Run a real Convex runtime check.

Safety notes: scripts, network and destructive changes

The skill does not run scripts and does not use the network, according to its listing. It does, however, guide changes that delete data. Its own rules say to use indexed and size-limited deletion, avoid bulk-clearing login sessions, and send large one-off production migrations or destructive backfills to convex-migration-helper.

Review every deletion path the agent writes before it reaches production. The skill lowers the risk of unbounded cleanup but does not remove the risk of destructive changes.

• No scripts are run and no network use is declared.
• Never run large production deletions without a reviewed migration plan.
• Read any generated cron job and delete query before merging.

Tips for getting good results

Give the agent the context the skill assumes. Point it at the target table and say whether the data is ephemeral or needs to be kept. Ask for the policy classification to be added as part of the same change, since the type check enforces it.

If the agent proposes a bulk delete of auth data, redirect it to the bounded pruning approach the skill describes.

• State whether the table is ephemeral and what its expiration field should be.
• Ask for tests alongside the cleanup code.
• Prefer expirationTime for new generic TTL tables, as the skill recommends, and keep existing fields unless a real migration is planned.