convex-file-storage
Complete file handling including upload flows, serving files via URL, storing generated files from actions, deletion, and accessing file metadata from system tables
68
60%
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-file-storage/SKILL.mdQuality
Discovery
42%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 lists specific file operations but fails to provide any guidance on when Claude should select this skill. The technical language ('system tables', 'actions') may not match natural user queries, and the lack of a 'Use when...' clause significantly weakens its utility for skill selection among many options.
Suggestions
Add a 'Use when...' clause with explicit triggers like 'Use when the user wants to upload, download, share, or manage files, or when working with file URLs and storage.'
Include more natural user terms such as 'download', 'save', 'share file', 'file link', 'attach', or common file extensions to improve trigger term coverage.
Clarify the context (e.g., what 'system tables' and 'actions' refer to) or replace with user-facing language to reduce ambiguity and improve distinctiveness.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'upload flows', 'serving files via URL', 'storing generated files from actions', 'deletion', and 'accessing file metadata from system tables'. 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. Per rubric guidelines, missing explicit trigger guidance caps completeness at 2, and this has no 'when' component at all. | 1 / 3 |
Trigger Term Quality | Contains some relevant keywords like 'upload', 'file', 'URL', 'deletion', 'metadata', but uses technical terms like 'system tables' and misses common user phrases like 'download', 'save file', 'get file', or file extensions. | 2 / 3 |
Distinctiveness Conflict Risk | The term 'file handling' is fairly generic and could overlap with document processing, data storage, or other file-related skills. The specific mentions of 'system tables' and 'URL serving' add some distinction but not enough to clearly carve out a unique niche. | 2 / 3 |
Total | 8 / 12 Passed |
Implementation
77%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 code examples covering the complete file storage workflow in Convex. The main weakness is length - at 300+ lines it could benefit from splitting advanced patterns (image preview, schema examples) into separate files. The workflow clarity is strong with explicit steps and validation patterns.
Suggestions
Split the 'Image Upload with Preview' and 'Schema for File Storage' sections into separate reference files (e.g., EXAMPLES.md) to reduce the main skill length
Remove the introductory bullet list under 'File Storage Overview' - Claude doesn't need this context and the code examples demonstrate these capabilities
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some unnecessary explanations (e.g., 'Convex provides built-in file storage with:' bullet list) and could be tightened. The code examples are good but there's redundancy between sections. | 2 / 3 |
Actionability | Excellent actionability with fully executable, copy-paste ready code examples covering the complete file handling workflow including upload URLs, client-side upload, saving references, serving files, and deletion. | 3 / 3 |
Workflow Clarity | Clear multi-step workflows with explicit sequencing (Step 1, 2, 3 in client upload), validation patterns (file type/size checks), and proper error handling patterns. The upload flow is well-documented with clear checkpoints. | 3 / 3 |
Progressive Disclosure | Content is well-organized with clear sections, but it's quite long and monolithic. The schema examples and image uploader with preview could be split into separate reference files. References to external docs are good but internal structure could benefit from splitting. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
75%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
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.