Content
86%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 instruction skill: exact commands with documented flags, a sequenced workflow with real validation and safety gating, and disciplined token economy. The remaining gaps are minor — no example form for the deferred repo/work-order commands and an implicit rather than explicit fix-retry loop for failed validation.
Suggestions
In step 4, include an example of what the migration status command looks like (or a snippet of the work-order section that contains it) so the step is executable without re-parsing the generated file.
Add an explicit feedback loop to step 3, e.g. "If format, tests, typecheck, or build fail, fix the changes and re-run before proceeding to the migration status check."
Show a short example structure of .emdash/UPGRADE.md (entry format, migration delta section) so step 2's assessment has a concrete pattern to match against.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Lean and information-dense with no padding or explanation of concepts Claude already knows — e.g. "The updater does not edit application code, apply database migrations, or deploy" and "A JSON backup is not a recovery point"; every sentence carries tool-specific or safety-critical information, matching the 'every token earns its place' anchor. | 5 / 5 |
Actionability | Provides copy-paste-ready commands ("npx upgrade-emdash@latest --dry-run") with fully documented flags ("--to does not accept a version", "--json for a machine-readable dry-run"), but steps 3–4 defer to repo- and work-order-specific commands ("Run the repository's relevant format, tests, typecheck, and build commands", "the migration status command from the work order") without an example form — minor gaps that keep it below fully-executable anchor 5. | 4 / 5 |
Workflow Clarity | A clear 7-step sequence with explicit validation checkpoints (step 3 tests/typecheck/build, step 4 migration status, step 7 migration check and site verification) and gating conditions ("Ask before applying a migration", backup required before database-changing steps). It falls short of anchor 5 only because the fix-and-retry feedback loop for failed validation in step 3 is implicit rather than explicit, though rollback recovery for the destructive path is stated. | 4 / 5 |
Progressive Disclosure | A simple under-50-line skill with no bundle files, well-organized into two clear sections ("Prepare the work order" / "Complete the upgrade"), and its single external reference (the Backups and recovery guide) is clearly signaled and one level deep — satisfying the simple-skill exception for a top score. | 5 / 5 |
Total | 18 / 20 Passed |