convex

Guidelines for developing with Convex backend-as-a-service platform, covering queries, mutations, actions, and real-time data patterns

Quality

41%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./convex/SKILL.md

Quality

Content

42%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill provides excellent, executable Convex code examples covering the major API surface, but is significantly bloated with non-Convex content (general TypeScript style, React patterns, UI frameworks) that Claude already knows. The monolithic structure with no progressive disclosure and minimal workflow guidance weakens its effectiveness as a reference document.

Suggestions

Remove the entire 'General Development Specifications' section (code style, error handling, UI framework integration) — these are not Convex-specific and Claude already knows them, saving ~40% of tokens.

Split into SKILL.md (quick start with query/mutation/action basics + best practices) and separate reference files like SCHEMA.md, HTTP_ROUTES.md, FILE_HANDLING.md, CRON_JOBS.md with clear navigation links.

Add validation/verification steps: e.g., how to verify schema changes deployed correctly, how to test queries in the Convex dashboard, what errors look like when indexes are missing.

Remove the 'You are an expert in...' preamble — it wastes tokens and doesn't add actionable guidance.

Dimension	Reasoning	Score
Conciseness	The skill is verbose and includes significant content Claude already knows: general TypeScript style guidelines, React patterns (Suspense, Server Components), UI framework preferences (Shadcn, Radix, Tailwind), basic error handling patterns, and naming conventions. These are not Convex-specific and waste token budget. The 'You are an expert in...' preamble is also unnecessary.	1 / 3
Actionability	The skill provides fully executable, copy-paste ready code examples for every Convex pattern: queries, mutations, actions, schema definitions, HTTP routes, cron jobs, and file handling. Each example is complete with imports and realistic usage.	3 / 3
Workflow Clarity	The file handling section shows a clear 3-step process, but most other sections are standalone patterns without sequencing or validation checkpoints. There's no guidance on error recovery, no validation steps after schema changes or deployments, and no feedback loops for debugging common issues.	2 / 3
Progressive Disclosure	The content is a monolithic wall of text with no references to external files and no clear separation between quick-start essentials and advanced topics. Everything from basic queries to cron jobs to UI framework preferences is dumped into a single file with no navigation structure.	1 / 3
	Total	7 / 12 Passed

Description

40%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description benefits from naming a specific platform (Convex), which makes it highly distinctive, but it lacks an explicit 'Use when...' clause and lists categories rather than concrete actions. The description reads more like a topic summary than actionable skill-selection guidance.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user is building with Convex, asks about Convex queries/mutations/actions, or needs help with real-time backend patterns in Convex.'

List more specific concrete actions, e.g., 'Define Convex schemas, write query and mutation functions, implement real-time subscriptions, configure scheduled functions, and set up authentication.'

Include additional natural trigger terms users might say, such as 'Convex database', 'Convex functions', 'convex.dev', 'serverless backend', or 'reactive data'.

Dimension	Reasoning	Score
Specificity	Names the domain (Convex backend-as-a-service) and some actions (queries, mutations, actions, real-time data patterns), but these are more like categories than concrete specific actions. It doesn't list things like 'define schema validators', 'set up real-time subscriptions', or 'configure authentication'.	2 / 3
Completeness	It describes what the skill covers ('Guidelines for developing with Convex...') but has no explicit 'Use when...' clause or equivalent trigger guidance. Per the rubric, a missing 'Use when...' clause should cap completeness at 2, and since the 'what' is also somewhat vague ('guidelines for developing'), this falls to 1.	1 / 3
Trigger Term Quality	Includes 'Convex' which is a strong trigger term, plus domain terms like 'queries', 'mutations', 'actions', and 'real-time data patterns'. However, it's missing common variations users might say like 'Convex database', 'Convex functions', 'convex.dev', 'serverless backend', or 'reactive queries'.	2 / 3
Distinctiveness Conflict Risk	The mention of 'Convex backend-as-a-service platform' is highly distinctive and creates a clear niche. It's unlikely to conflict with other skills since Convex is a specific named platform.	3 / 3
	Total	8 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: mindrally/skills
Path: convex/SKILL.md
Commit: 05a7130

Reviewed: about 4 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.