convex-suggest — Claude Code skill: suggests Convex components
The skill notices when you hand-roll something a ready Convex component already solves, and offers one match after your task is done.
npx skills add convex/agent-skills --skill convex-suggest -a claude-codeWhat convex-suggest does
It watches your code snippets and your ask passively, without blocking the current task. When a pattern shows up that a component already covers, it waits until the task is finished, then names one component, quotes the exact line that triggered it, and explains why the component fits better. Spot post.likes + 1 inside a mutation many users call at once, and it will point at OCC conflicts under load.
Detector rules map the patterns: setInterval or cron to @convex-dev/crons, shared counter increments to @convex-dev/sharded-counter, .collect().length scans to @convex-dev/aggregate, long-running multi-step actions to @convex-dev/workflow, bounded concurrency to @convex-dev/workpool, rate-limit counters in the database to @convex-dev/rate-limiter, file uploads to Convex Storage, Elasticsearch or Algolia to built-in full-text search, presence and typing to @convex-dev/presence, an external vector database to @convex-dev/rag, collaborative editing to @convex-dev/prosemirror-sync.
The skill never installs anything on its own. Say yes and it runs /add <component> or follows the detector's install hint. Say no or ignore it and the suggestion is dropped for good. On generic coding questions unrelated to Convex, it stays quiet.
What it helps with
- replace a hand-rolled like counter with sharded-counter
- move a cron job onto
@convex-dev/crons - drop
.collect().lengthscans in favour of aggregate - swap homemade database counters for rate-limiter
- route long multi-step actions through workflow
Example prompts for the agent
- I just finished a mutation that increments likes — check whether a Convex component already does this
- Look at my code for cron jobs and tell me if there's a matching component
- Is there a Convex component for presence and typing if I'm writing it myself?
How to install convex-suggest
1Skills CLI (Vercel)
npx skills add convex/agent-skills --skill convex-suggest -a claude-code2Manually: put the files in place
~/.claude/skills/convex-suggest/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/convex-suggest/
1Skills CLI (Vercel)
npx skills add convex/agent-skills --skill convex-suggest -a codex2Manually: put the files in place
.agents/skills/convex-suggest/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add convex/agent-skills --skill convex-suggest -a cursor2Manually: put the files in place
.cursor/skills/convex-suggest/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install convex/agent-skills convex-suggest2Manually: put the files in place
.github/skills/convex-suggest/SKILL.md1Skills CLI (Vercel)
npx skills add convex/agent-skills --skill convex-suggest -a gemini-cli2Platform CLI
gemini skills install https://github.com/convex/agent-skills --path skills/convex-suggestManually: put the files in place
.devin/skills/convex-suggest/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add convex/agent-skills --skill convex-suggest -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about convex-suggest
How do I install convex-suggest in Claude?
Run npx skills add convex/agent-skills --skill convex-suggest -a claude-code. The skill lands in ~/.claude/skills/convex-suggest/SKILL.md.
What does convex-suggest do?
It reads your code and ask, then after the task is done suggests one Convex component that covers the pattern you wrote by hand. It never installs without your consent.
Will the skill install the component for me?
No. It names the component and gives the reason, then installs only after an explicit yes — via /add <component> or the detector's hint.
Source text
SKILL.md · Apache-2.0
--- name: convex-suggest description: "Suggest the matching Convex component when the user hand-rolls a pattern it already solves (crons, sharded-counter, rate-limiter, storage, search, presence, workflow, RAG, prosemirror-sync). Passive — suggest after the task, never interrupt. Never install without consent." --- <!-- GENERATED from convex-agents content/capabilities/suggest.json — do not edit by hand. --> # Proactively suggest the right Convex component When you see code or intent that duplicates what a Convex component already does, surface a targeted suggestion: ONE component, WHY (anchored in the user's own code or ask), and a concrete install hint. Never install without explicit consent. Never suggest more than one component at a time unless the user asks. ## Workflow 1. Observe the codeSnippets and userAsk passively — never block the current task to suggest. 2. Match against the detector rules (see generators/suggest-detector.mjs): email/SMTP → resend; push notifications → expo-push; setInterval/cron → @convex-dev/crons; shared counter increments → @convex-dev/sharded-counter; .collect().length scans → @convex-dev/aggregate; multi-step/long-running actions → @convex-dev/workflow; bounded concurrency → @convex-dev/workpool; rate-limit counters in DB → @convex-dev/rate-limiter; fs.write/S3 uploads → Convex Storage; Elasticsearch/Algolia → built-in full-text search; presence/typing → @convex-dev/presence; Pinecone/external vector DB → @convex-dev/rag; collaborative editing → @convex-dev/prosemirror-sync. 3. After finishing the current task, offer ONE suggestion: name the component, quote the specific code or phrase that triggered it, explain why the component fits better. 4. If the user says yes: run `/add <component>` or follow the installHint from the detector. 5. If the user says no or ignores it: drop it. Do not repeat the same suggestion. ## Rules - Passive — never interrupt the current task; surface the suggestion AFTER completing what the user asked. - One at a time — pick the highest-priority match; do not dump a list of five components. - Cite WHY from the user's own code or ask — 'I noticed you wrote `post.likes + 1` in a mutation that many users call concurrently; that causes OCC conflicts at scale.' - Never install without explicit consent — suggest, explain, wait for a yes. - Do not suggest a component the user has already installed. - Do not fire on generic coding questions unrelated to Convex (sorting arrays, writing CSS, etc.).
© convex · Apache-2.0 · convex/agent-skills
