Content
81%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.
An excellent instruction-only skill body: a seven-phase lifecycle with operator gates, dry-run-first safety rules, verification steps, and concrete validation commands. Weaknesses are minor — some deliberate repetition of the confirmation gates and delegation of the actual migration command shapes to companion skills rather than showing them.
Suggestions
Consolidate the repeated confirmation-gate language (stated in Safety Rules, Phase 5, and Phase 6) into a single authoritative statement to trim token usage without losing safety.
Include one concrete example command shape for a production dry run and apply (e.g., the `@convex-dev/migrations` runner invocation) so the core steps are executable without consulting companion skills.
Move the detailed per-phase checklists (e.g., Phase 5 result-presentation fields and Phase 7 cleanup lists) into a one-level-deep reference file to shorten the always-loaded SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, checklist-driven, and assumes Convex competence — no space is spent explaining concepts Claude already knows. However, the destructive-apply and cleanup-removal confirmation gates are each stated two or three times (Safety Rules, Phase 5 step 4, Phase 6 step 1), and bounded-batch resumption appears in both Phase 5 and Phase 6; this deliberate but trimmable duplication keeps it at anchor 4 ('minor instances... that could be trimmed') rather than 5. | 4 / 5 |
Actionability | Concrete executable commands are given for validation (`bunx convex codegen`, `bunx tsc --noEmit`, `bun run ci:static`, `bunx convex dev --once`, `convex run`) plus specific result fields (`isDone`, `dryRun`, resume cursors, confirmation token), matching 'mostly executable guidance with minor gaps'. Not a 5 because the actual dry-run/apply command shapes are delegated to `@convex-dev/migrations` and companion skills rather than shown, so nothing is copy-paste ready for the core production steps. | 4 / 5 |
Workflow Clarity | Seven clearly sequenced phases with explicit validation checkpoints at every gate: local validation ladder before PR, deploy success before dry run, dry-run results presented before apply, explicit user confirmation before both apply and cleanup removal, verification proving zero remaining targets, and resume-until-isDone feedback loops with documented safety caps. This matches anchor 5 (explicit validation steps, error-recovery loops, checklists for a complex destructive process); the destructive-operation cap of 3 does not apply since validation is pervasive. | 5 / 5 |
Progressive Disclosure | The body is well organized into scannable phase sections and appropriately delegates detail to companion skills (`convex-migration-helper`, `clawhub-convex`, `clawhub-production-release`) rather than inlining it. It stays at anchor 4 rather than 5 because at ~170 lines it is a single monolithic file with no one-level-deep bundled references (no references/ or scripts/ exist), and some per-phase detail checklists could be split out to shorten the always-loaded overview. | 4 / 5 |
Total | 17 / 20 Passed |