convex-best-practices
Guidelines for building production-ready Convex apps covering function organization, query patterns, validation, TypeScript usage, error handling, and the Zen of Convex design philosophy
66
56%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/convex-best-practices/SKILL.mdQuality
Discovery
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 identifies a clear niche (Convex development) and lists relevant topic areas, making it distinguishable from other skills. However, it reads more like a table of contents than actionable guidance, lacking concrete actions and completely missing explicit trigger conditions for when Claude should select this skill.
Suggestions
Add a 'Use when...' clause specifying triggers like 'when building Convex applications', 'when asking about Convex functions', 'when mentioning real-time backends with Convex'
Convert topic categories into concrete actions: instead of 'function organization', use 'organize Convex functions into modules' or 'structure query and mutation handlers'
Include common user phrasings like 'Convex backend', 'Convex database queries', 'real-time sync', or 'serverless Convex functions'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Convex apps) and lists several topic areas (function organization, query patterns, validation, TypeScript usage, error handling), but these are categories rather than concrete actions. Missing action verbs like 'create', 'implement', 'configure'. | 2 / 3 |
Completeness | Describes what the skill covers (guidelines for Convex apps) but completely lacks a 'Use when...' clause or any explicit trigger guidance. Per rubric guidelines, missing explicit trigger guidance should cap completeness at 2, and this has no 'when' component at all. | 1 / 3 |
Trigger Term Quality | Includes 'Convex' which is the key domain term, plus relevant technical terms like 'query patterns', 'validation', 'TypeScript'. However, missing common variations users might say like 'Convex backend', 'Convex database', 'real-time app', or 'serverless functions'. | 2 / 3 |
Distinctiveness Conflict Risk | Clearly targets Convex specifically, which is a distinct technology. The mention of 'Zen of Convex design philosophy' further narrows the scope. Unlikely to conflict with general TypeScript or other backend framework skills. | 3 / 3 |
Total | 8 / 12 Passed |
Implementation
72%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a solid skill with excellent actionable code examples and good organization. The main weaknesses are some verbosity in explanatory sections (like 'The Zen of Convex') and lack of explicit workflow validation steps for multi-step operations like deployment or schema changes.
Suggestions
Remove or significantly condense 'The Zen of Convex' section - these are abstract principles Claude doesn't need explained
Add explicit validation checkpoints for workflows like 'after defining schema, run npx convex dev to validate types before writing functions'
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient but includes some unnecessary explanation like 'The Zen of Convex' philosophy section and verbose descriptions. The code examples are good but some surrounding text could be tightened. | 2 / 3 |
Actionability | Excellent executable code examples throughout - complete CRUD patterns, schema definitions, query patterns, and error handling are all copy-paste ready with proper imports and type annotations. | 3 / 3 |
Workflow Clarity | The content provides good patterns but lacks explicit validation checkpoints. The 'Instructions' section tells what to do but doesn't sequence operations with verification steps. Missing feedback loops for error recovery. | 2 / 3 |
Progressive Disclosure | Well-organized with clear sections (Code Quality, Instructions, Examples, Best Practices, Common Pitfalls, References). External documentation links are clearly signaled and one level deep. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 13 / 16 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
description_trigger_hint | Description may be missing an explicit 'when to use' trigger hint (e.g., 'Use when...') | Warning |
metadata_version | 'metadata' field is not a dictionary | Warning |
license_field | 'license' field is missing | Warning |
Total | 13 / 16 Passed | |
- Repository
- waynesutton/convexskills
- Commit
8ef49c9
- Reviewed
Table of Contents
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.