Convex Agent Skills

Agent skills for common Convex workflows.

Install

# Choose which skills you want
npx skills add get-convex/agent-skills

# OR Install all skills
npx skills add get-convex/agent-skills --all

Usage

Skills are applied automatically when the agent determines they're relevant. How
you manually invoke them depends on your tool:

Tool	Manual invocation
Cursor	/skill-name
VS Code (GitHub Copilot)	/skill-name
Claude Code	/skill-name
Windsurf	@skill-name
Codex (OpenAI)	$skill-name

For example, to kick off auth setup in Cursor or Claude Code:

/convex-setup-auth

In Windsurf:

@convex-setup-auth

Available Skills

• convex - Top-level entry point for Convex work. Recommends installing Convex AI files, then routes to a more specific Convex skill.
• convex-quickstart - Start a new Convex project or add Convex to an existing app.
• convex-setup-auth - Set up authentication for a Convex app.
• convex-create-component - Build a reusable Convex component with clear boundaries.
• convex-migration-helper - Plan and run Convex migrations safely.
• convex-performance-audit - Investigate Convex performance problems and bottlenecks.

Skill Philosophy

Skills in this repo should be laser-focused on a specific task or workflow.

A good skill helps an agent take action, for example:

• set up authentication
• create a component
• perform a migration
• diagnose performance issues

A skill should not exist just to provide generic background information. If content is mostly reference material, it should usually live in documentation, not as a standalone skill.

Reference material is still useful inside a skill, but only when it helps the agent complete a concrete task.

Contributing

Before contributing, review the core Agent Skills docs:

• Overview
• What are skills?
• Specification
• Optimizing skill descriptions
• Evaluating skill output quality

If your skill bundles scripts, also read Using scripts in skills.

Install dependencies once with npm install, then use:

• npm run format to rewrite files
• npm run format-check to verify formatting before opening a PR

Validating Skills

Validate skills by trying to use them in a realistic temp project, not just by reading them.

• Push the skill as far as possible with an agent in a throwaway directory
• If a human must intervene, ask explicitly for the exact action needed and then continue
• Record what worked, where the agent got stuck, and what confused the flow
• Feed those learnings back into the skill so the next run is better
• For UI-facing skills such as auth setup, validate the actual browser flow during skill development, not just code generation or a successful build

Testing with Anthropic's Skill Creator

For a more rigorous approach, use Anthropic's skill-creator skill. It provides a structured loop for testing and iterating on skills:

1. Draft or edit a skill
2. Define realistic test prompts and run the skill against them (with and without the skill as a baseline)
3. Grade the outputs with assertions and review them in a browser-based viewer
4. Improve the skill based on feedback, then repeat

It also includes a description optimizer that tunes the skill's frontmatter description for better triggering accuracy across different phrasings.

Install it in Claude Code:

/install-skill https://github.com/anthropics/skills/tree/main/skills/skill-creator

This is especially useful when a skill is complex enough that reading it alone won't tell you if it actually works well in practice.

Each skill follows the Agent Skills open standard:

1. Create a directory under skills/ with the skill name
2. Add a SKILL.md file with YAML frontmatter:

   ---
   name: skill-name
   description: Brief description
   ---
   

3. Include comprehensive examples with bad/good patterns
4. Add a checklist at the end of each skill
5. Update this root README.md whenever skills are added, removed, renamed, or substantially repositioned