Content
71%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A tight, well-structured skill that captures the safe migration ordering (optional, backfill, verify, then tighten) with strong guardrail rules. Its weakness is actionability: no executable commands or code examples for installing the migrations package, writing a migration function, running it, or verifying rows.
Suggestions
Add executable commands for each step: the npm/pnpm install command for @convex-dev/migrations, the CLI command to run the migration, and a concrete validation query to verify rows are valid.
Include a minimal migration function example showing the expected shape of a backfill migration.
Add an error-recovery feedback loop for step 3 (what to do when row verification fails), and deduplicate the Rules that restate workflow steps.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumes Claude's competence: no concept explanations, no padding, every section instructs. It is not level 5 because the Rules section partially restates the workflow ("Add new fields as optional first, migrate, then require" duplicates workflow steps 1 and 4), leaving minor redundancy that could be trimmed. | 4 / 5 |
Actionability | The strategy is concrete (optional first, backfill, then require) and names the package, but there is no executable code or command anywhere: no install command, no migration function example, no run command, and no concrete verification command. This matches the anchor for some concrete guidance that is incomplete with missing key details; it exceeds level 2 because the ordering and package choice are specific, not just high-level hints. | 3 / 5 |
Workflow Clarity | A clear four-step sequence with validation checkpoints present ("Run the migration; verify all rows are valid", "Verify row counts before and after", and the never-tighten-early rule). Validation steps exist, so the destructive/batch cap of 3 does not apply, but there is no explicit error-recovery feedback loop (what to do when verification fails) and verification lacks a concrete command, keeping it below level 5. | 4 / 5 |
Progressive Disclosure | The skill is under 50 lines, has no external bundle files, and needs none at this size; sections are well-organized (overview, Workflow, Rules). Per the guidelines, this qualifies for a top score with just well-organized sections. | 5 / 5 |
Total | 16 / 20 Passed |