Content
85%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, operationally precise runbook: exact CLI invocations with flag-level gotchas, a correctly ordered rehearsal workflow with explicit validation gates and feedback loops, and honest treatment of destructive-risk details (fresh consent, rollback artifact, data-loss window, snapshot sensitivity). The only notable weaknesses are moderate redundancy between the Rules and Workflow sections and high-level direction on the two trickiest authoring steps (backfill and schema edit).
Suggestions
Trim the Rules section to points not already stated verbatim in the Workflow (e.g. keep only the sensitive-snapshot and @convex-dev/migrations rules) to cut redundancy.
Add a minimal example of the optional-then-tighten schema.ts change and a skeletal @convex-dev/migrations backfill definition so the two hardest steps are executable rather than directed.
State the migrate-order rule once, in one place, rather than in both step 4 and the Rules section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with operational specifics — exact CLI flags, deployment-name targeting, key preconditions — and explains only Convex-specific gate behavior Claude cannot be assumed to know, not general concepts. It is not a 5 because the Rules section restates roughly half a dozen points already made in the Workflow (pre-change preview creation, --preview-name vs --deployment, fresh explicit yes, snapshot rollback caveat, snapshot sensitivity), which is more than trivially trimmable redundancy. | 4 / 5 |
Actionability | Concrete, copy-paste-ready commands with exact flags appear at every step (`npx convex export --path snapshot.zip`, `npx convex deploy --preview-create migrate-<slug>`, `npx convex import snapshot.zip --deployment migrate-<slug>`, `--preview-name`, `import ... --replace --prod`), plus gotchas like the missing --preview-name flag on import. It is not a 5 because the two hardest steps — authoring the @convex-dev/migrations backfill and the optional-then-tighten schema edit — are directed at a high level with no example snippet, leaving minor gaps. | 4 / 5 |
Workflow Clarity | The numbered 0–7 sequence is explicit with validation checkpoints and feedback loops exactly where the destructive/batch risk lives: the conformance gate fails on the preview copy with "fix and re-push until green", step 5 verifies behavior against migrated data, and the prod promote is gated on a fresh explicit yes and is a repeat of the proven run. Rollback (snapshot --replace) and data-loss caveats are stated plainly. This matches the top anchor: clear sequence, explicit validation, error-recovery loops for a batch/destructive process. | 5 / 5 |
Progressive Disclosure | There are no bundle files (no references/, scripts/, or assets/), and the ~30-line body is well organized into a Workflow and Rules section with everything needed inline; per the rubric, a sub-50-line self-contained skill with well-organized sections scores 5. No content belongs in separate files and no nested or buried references exist. | 5 / 5 |
Total | 18 / 20 Passed |