get-convex /agent-skills

33 chapters · 70 min

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:

In Windsurf:

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 (opens in a new tab)
• What are skills? (opens in a new tab)
• Specification (opens in a new tab)
• Optimizing skill descriptions (opens in a new tab)
• Evaluating skill output quality (opens in a new tab)

If your skill bundles scripts, also read Using scripts in skills (opens in a new tab).

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 (opens in a new tab) 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:

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 (opens in a new tab):

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

   yamlCopy

   ---
   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