convex-agents

Building AI agents with the Convex Agent component including thread management, tool integration, streaming responses, RAG patterns, and workflow orchestration

Quality

57%

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-agents/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 comprehensive skill with excellent actionable code examples covering the full Convex Agent API surface. However, it's verbose with some unnecessary explanatory sections, and the workflow examples lack explicit validation checkpoints and error recovery patterns that would be important for production agent implementations.

Suggestions

Remove the 'Why Convex for AI Agents' section - Claude doesn't need to be sold on the benefits; jump straight to implementation

Add explicit validation and error handling steps in the workflow orchestration example (e.g., 'If search returns no results: handle gracefully', 'Validate analysis before proceeding')

Move the React component and full schema examples to separate reference files (e.g., REACT_EXAMPLE.md, SCHEMA.md) and link to them from the main skill

Add a feedback loop pattern showing how to retry failed tool calls or handle partial failures in multi-step workflows

Dimension	Reasoning	Score
Conciseness	The skill includes some unnecessary explanatory content like the 'Why Convex for AI Agents' section that explains benefits Claude already understands. The code examples are good but could be tighter - some sections like the React component are verbose for a backend-focused skill.	2 / 3
Actionability	Excellent executable code examples throughout - complete TypeScript implementations for thread management, tool integration, RAG, and workflows. All code is copy-paste ready with proper imports, types, and return values specified.	3 / 3
Workflow Clarity	Multi-step processes like the research workflow are shown but lack explicit validation checkpoints. The workflow orchestration example updates status but doesn't include error handling or validation steps between stages. Missing feedback loops for error recovery.	2 / 3
Progressive Disclosure	Content is reasonably organized with clear sections, but the skill is quite long (~400 lines) with inline content that could be split into separate reference files. The References section at the end is good, but detailed examples like the React component and full schema could be in separate files.	2 / 3
	Total	9 / 12 Passed

Description

50%

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 effectively communicates specific capabilities for building AI agents with Convex and names the technology clearly, creating good distinctiveness. However, it critically lacks explicit trigger guidance ('Use when...') which would help Claude know when to select this skill, and could benefit from more natural user-facing keywords beyond technical jargon.

Suggestions

Add a 'Use when...' clause specifying triggers like 'when building agents with Convex', 'when the user mentions Convex Agent', or 'when implementing conversational AI on Convex'

Include natural language variations users might say: 'chatbot', 'assistant', 'conversation threads', 'agent memory', 'Convex backend'

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: 'thread management, tool integration, streaming responses, RAG patterns, and workflow orchestration' - these are distinct, actionable capabilities.	3 / 3
Completeness	Describes what the skill does but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill.	1 / 3
Trigger Term Quality	Contains relevant technical terms like 'AI agents', 'Convex Agent', 'RAG', 'streaming' but missing common user variations like 'chatbot', 'assistant', 'conversation history', or file extensions.	2 / 3
Distinctiveness Conflict Risk	'Convex Agent component' is a specific technology that creates a clear niche; unlikely to conflict with generic agent-building or other framework-specific skills.	3 / 3
	Total	9 / 12 Passed

Validation

68%

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 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (517 lines); consider splitting into references/ and linking	Warning
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	11 / 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.