convex-functions

Writing queries, mutations, actions, and HTTP actions with proper argument validation, error handling, internal functions, and runtime considerations

Quality

44%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Fix and improve this skill with Tessl

tessl review fix ./skills/convex-functions/SKILL.md

Quality

Content

64%

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, actionable skill with excellent executable code examples covering all Convex function types. The main weaknesses are moderate verbosity (the overview table and documentation links section add tokens without proportional value) and missing explicit validation/error recovery workflows for complex multi-step operations like payment processing.

Suggestions

Remove or condense the 'Documentation Sources' section - Claude can fetch docs when needed without listing every URL upfront

Add explicit validation checkpoints to the processOrder action example (e.g., 'If payment fails, do X; if mutation fails after payment succeeds, do Y')

Move the 'Complete Function File' example to a separate EXAMPLES.md file and reference it from the main skill

Dimension	Reasoning	Score
Conciseness	The skill is reasonably efficient but includes some redundancy - the function types table duplicates information explained in subsequent sections, and the 'Documentation Sources' section with multiple URLs adds tokens without immediate actionable value. The examples are good but could be slightly tighter.	2 / 3
Actionability	Excellent executable code examples throughout - all TypeScript snippets are complete, copy-paste ready with proper imports, validators, and handlers. The examples cover queries, mutations, actions, HTTP actions, internal functions, and scheduling with realistic use cases.	3 / 3
Workflow Clarity	The function types overview table provides good sequencing guidance, and the examples show proper patterns (validate user exists before creating task, verify webhook signature before processing). However, there are no explicit validation checkpoints or feedback loops for error recovery in multi-step processes like the processOrder action.	2 / 3
Progressive Disclosure	The skill references external documentation and another skill file (convex-best-practices), but the main content is quite long (~300 lines) with extensive inline examples. The 'Complete Function File' example could be in a separate file. Structure is good with clear sections but content could be better split.	2 / 3
	Total	9 / 12 Passed

Description

25%

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

This description lists technical concepts but fails to identify the specific technology/framework it applies to, making it indistinguishable from generic backend development skills. It lacks explicit trigger guidance ('Use when...') and uses terms that are common across many technologies, creating high conflict risk with other skills.

Suggestions

Add explicit technology context (e.g., 'Convex backend development' or similar) to distinguish from generic query/mutation skills

Add a 'Use when...' clause with specific triggers like 'Use when working with Convex functions, backend queries, or server-side actions'

Include file extensions or project indicators that would help Claude identify when this skill applies (e.g., 'convex/ directory', '.ts files in convex folder')

Dimension	Reasoning	Score
Specificity	Names the domain (queries, mutations, actions, HTTP actions) and mentions some aspects (argument validation, error handling, internal functions, runtime considerations), but these are somewhat abstract concepts rather than concrete actions like 'create', 'debug', or 'optimize'.	2 / 3
Completeness	Describes what the skill covers but completely lacks any 'Use when...' clause or explicit trigger guidance. There's no indication of when Claude should select this skill over others.	1 / 3
Trigger Term Quality	Includes relevant technical terms like 'queries', 'mutations', 'actions', 'HTTP actions' that users might say, but lacks common variations or natural language triggers. Missing context about what framework/platform this applies to (appears to be Convex but never stated).	2 / 3
Distinctiveness Conflict Risk	Terms like 'queries', 'mutations', 'actions', and 'error handling' are extremely generic and could apply to GraphQL, REST APIs, database operations, or any backend framework. Without specifying the platform/technology, this would conflict with many other skills.	1 / 3
	Total	6 / 12 Passed

Validation

75%

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 — 12 / 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	12 / 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.