mirror of
https://github.com/get-convex/agent-skills.git
synced 2026-09-14 19:28:17 +08:00
Mikael Lirbank
151 lines
5.0 KiB
Markdown
151 lines
5.0 KiB
Markdown
# 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](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](THIRD_PARTY_NOTICES.md) for details.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
# 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](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
|