Convex Agent Skills

Agent skills for common Convex workflows.

License

Unless otherwise noted, all original content in this repository is licensed under the Apache License 2.0. This includes the skill instructions, reference documentation, and source code in revisions that include this license. It does not retroactively change the licensing of earlier revisions.

Third-party materials remain under their respective licenses. See THIRD_PARTY_NOTICES.md for details.

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:

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 pnpm install, then use:

• pnpm format to rewrite files
• pnpm 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