Content
45%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.
The skill has a well-gated core workflow but is undermined by heavy verbosity, inline reference material that belongs in separate files, code examples with undefined methods, and a Quick Start that points to bundle files that do not exist. It reads more like a textbook chapter than a navigable, executable skill overview.
Suggestions
Trim the generic conceptual material Claude already knows (migration pattern catalogs, risk categories, best-practices lists, pre/during/post-migration checklists) and keep only the executable Quick Start plus the Gate criteria in the body.
Create the referenced bundle files (scripts/migration_planner.py, compatibility_checker.py, rollback_generator.py, assets/sample_database_migration.json, assets/database_schema_before.json, assets/database_schema_after.json, expected_outputs/) or remove the references, since the broken paths make the workflow non-executable.
Move the pattern catalog, risk-assessment framework, and runbook checklists into separate reference files (e.g. references/patterns.md, references/runbooks.md) and link to them one level deep from SKILL.md, leaving the body as a concise overview.
Replace the illustrative Python class snippets with either complete executable examples or a note that they are conceptual sketches, so the inline code is not mistaken for copy-paste-ready guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | At ~425 lines the body extensively explains concepts Claude already knows (Expand-Contract, Strangler Fig, CDC, risk categories, best-practices lists, runbook checklists), matching the 'noticeably verbose; several unnecessary explanations or padded sections' anchor; the concise Quick Start cannot offset the bulk of padded reference material. | 2 / 5 |
Actionability | The Quick Start gives concrete CLI commands, but the referenced scripts/assets do not exist and the inline Python examples (MigrationCircuitBreaker, MigrationFeatureFlag) call undefined methods like new_service.process, should_attempt_reset, fallback_to_legacy, so guidance is incomplete/pseudocode-like per the 'some concrete guidance but incomplete' anchor. | 3 / 5 |
Workflow Clarity | The Quick Start sequences plan -> compatibility check -> rollback with an explicit Gate ('not approved until compatibility_checker exits 0... and a rollback runbook exists for every phase') and a re-run feedback loop ('Re-run both checks after any schema revision'), placing it above the midpoint; not 5 because validation outside the Quick Start is only implicit checklist items. | 4 / 5 |
Progressive Disclosure | Although sectioned, the body inlines large catalogs (pattern reference, risk framework, runbook checklists, tools list) that belong in separate files, and every referenced bundle path (scripts/*.py, assets/*.json, expected_outputs/) is missing, so references are broken rather than clearly signaled, matching the 'content that clearly belongs in separate files is inlined; references buried/missing' anchor. | 2 / 5 |
Total | 11 / 20 Passed |