convex-migrations
Schema migration strategies for evolving applications including adding new fields, backfilling data, removing deprecated fields, index migrations, and zero-downtime migration patterns
76
72%
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-migrations/SKILL.mdQuality
Discovery
67%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 excels at specificity by listing concrete migration strategies and has a clear, distinct niche. However, it lacks explicit trigger guidance ('Use when...') which limits Claude's ability to know when to select this skill, and could benefit from additional natural language variations users might employ when asking about database schema changes.
Suggestions
Add a 'Use when...' clause with trigger scenarios like 'Use when the user asks about database schema changes, evolving data models, or migrating production databases'
Include common term variations such as 'database migration', 'alter table', 'schema changes', 'DB schema evolution', or 'migrate database' to improve trigger term coverage
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'adding new fields, backfilling data, removing deprecated fields, index migrations, and zero-downtime migration patterns' - these are all distinct, actionable capabilities. | 3 / 3 |
Completeness | Clearly answers 'what does this do' with specific migration strategies, but lacks an explicit 'Use when...' clause or equivalent trigger guidance to indicate when Claude should select this skill. | 2 / 3 |
Trigger Term Quality | Contains relevant technical terms like 'schema migration', 'backfilling', 'index migrations', 'zero-downtime' that users might say, but misses common variations like 'database migration', 'alter table', 'schema changes', 'DB schema', or 'migrate database'. | 2 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on schema migrations with distinct triggers like 'backfilling data', 'zero-downtime migration', and 'index migrations' - unlikely to conflict with general database or code skills. | 3 / 3 |
Total | 10 / 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 high-quality, actionable skill for Convex migrations with excellent executable code examples and clear multi-step workflows. The main weakness is its length and verbosity - it could be more concise by removing explanatory text Claude already knows and splitting detailed examples into separate reference files. The migration runner pattern and tracking system are particularly well-designed with proper error handling and progress tracking.
Suggestions
Remove or significantly condense the 'Migration Philosophy' section - Claude understands these concepts and they add ~100 tokens of explanation
Consider splitting the detailed migration patterns (adding fields, removing fields, renaming, type changes) into a separate PATTERNS.md file, keeping only quick-reference summaries in the main skill
Remove inline comments that explain obvious code behavior (e.g., '// New field - start as optional', '// Handle missing field gracefully')
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but verbose in places. The migration philosophy section explains concepts Claude likely knows, and some code examples include redundant comments. However, most content is necessary for the complex migration patterns being taught. | 2 / 3 |
Actionability | Excellent actionability with fully executable TypeScript code examples throughout. Every migration pattern includes complete, copy-paste ready code with proper imports, type definitions, and return validators. The step-by-step progressions are concrete and implementable. | 3 / 3 |
Workflow Clarity | Outstanding workflow clarity with explicit numbered steps for each migration type (adding fields, removing fields, renaming, type changes). Each workflow includes validation checkpoints like 'After backfill completes' and 'Only when valid'. The migration runner pattern provides a complete feedback loop with status tracking. | 3 / 3 |
Progressive Disclosure | The skill is well-organized with clear sections, but it's quite long and monolithic. The documentation sources are listed upfront, but the extensive code examples could benefit from being split into separate reference files. The content is all inline rather than appropriately distributed. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
68%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 (713 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
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.