How to use the Convex Database Seeding agent skill

What is an agent skill and what does convex-seed do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a task matches the skill's description. The convex-seed skill has the name convex-seed and the description "Seed or import data into the Convex database."

When the skill is active, the agent knows how to populate tables in a Convex project. It can write an internalMutation seed function that inserts sample rows and run it with npx convex run. For larger datasets it can shape data to match your schema and use npx convex import. The instructions ask the agent to make seeding idempotent, using clear-then-insert or upsert, so running it again is safe. It also verifies row counts afterward.

Install the convex-seed skill

Download the ZIP for the skill from this page and unzip it. The skill folder should contain SKILL.md. Then place it in one of these locations:

Personal skills folder: ~/.claude/skills/ (available across your projects).

Project skills folder: .claude/skills/ inside your project (available only in that project).

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Download the ZIP from this page and unzip it.
• Copy the unzipped skill folder into ~/.claude/skills/ or your project's .claude/skills/ folder.
• Or upload the skill in the Claude apps under Settings → Capabilities → Skills.

Check the requirements before you start

The skill assumes a working Convex setup. Confirm that you have each item below before asking the agent to seed data.

• Node.js and npm, because the instructions use npx.
• A Convex project with a defined schema, since seed data must match the table validators.
• Convex CLI access to a deployment, so commands like npx convex run and npx convex import can reach it.

Trigger the skill with natural requests

You do not need a special command. Describe the task in plain language that mentions Convex and data, and the agent should pick up the skill. Be specific about the table and the size of the dataset so the agent chooses the right method: a seed function for fixtures, or an import for bulk records.

• "Seed my Convex database with 50 sample users for local testing."
• "Write an idempotent seed function that fills the projects and tasks tables with starter data."
• "Prepare a data file that matches my schema and import it into my Convex staging deployment with the Convex CLI."
• "After seeding, check how many rows are in each table."

Understand the workflow the agent follows

The skill sets out a fixed sequence. For fixtures, the agent writes an internalMutation that inserts sample rows and runs it with npx convex run. For bulk import, it shapes the data to the schema and uses npx convex import. In both cases it aims to make the seeding repeatable and then verifies row counts.

Read the agent's plan before it runs anything. The skill's rules say to seed through internalMutation or convex import, to match validators, and never to seed secrets or personal data into a shared deployment.

• Write an internalMutation that inserts sample rows (fixtures).
• Shape data to the schema and use npx convex import (bulk import).
• Make seeding idempotent with clear-then-insert or upsert.
• Verify row counts.

Safety notes: scripts and network access

This skill runs scripts and uses the network. The commands it uses talk to your Convex deployment, so the agent will reach whatever deployment your Convex CLI is configured for. Check which deployment is selected before you approve a run, especially if you have production and staging projects.

The skill is not suitable for production databases with real user data. An unreviewed seed or import could overwrite or corrupt records. Review every step the agent proposes, and never put secrets or personal data into a shared database.

• Confirm the target deployment before approving any npx convex run or npx convex import.
• Do not use the skill against production data.
• Keep secrets and personal data out of seed files and shared deployments.

Tips for reliable seeding

Ask for idempotent seeding every time, so you can rerun the seed during development without duplicating rows. Keep your seed data in version control so the same fixtures can be reproduced. If the schema changes, ask the agent to update the seed data so the validators still match.

• Name the target table and deployment in your request.
• Ask for a re-runnable seed function rather than a one-off insert.
• Check the row counts the agent reports against what you expect.