# 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](https://github.com/get-convex/agent-skills/blob/HEAD/LICENSE). 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](https://github.com/get-convex/agent-skills/blob/HEAD/THIRD_PARTY_NOTICES.md) for details.
## Install
```bash
# Choose which skills you want
npx skills add convex/agent-skills
# OR Install all skills
npx skills add 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](https://agentskills.io/home)
- [What are skills?](https://agentskills.io/what-are-skills)
- [Specification](https://agentskills.io/specification)
- [Optimizing skill descriptions](https://agentskills.io/skill-creation/optimizing-descriptions)
- [Evaluating skill output quality](https://agentskills.io/skill-creation/evaluating-skills)
If your skill bundles scripts, also read
[Using scripts in skills](https://agentskills.io/skill-creation/using-scripts).
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](https://github.com/anthropics/skills/tree/main/skills/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:
```bash
/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](https://github.com/anthropics/skills):
1. Create a directory under `skills/` with the skill name
2. Add a `SKILL.md` file with YAML frontmatter:
```yaml
---
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
