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

Quality

56%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

tessl review fix ./skills/convex-best-practices/SKILL.md

Quality

Content

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

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 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

Validation

81%

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 — 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: 5 months 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.