Content
63%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 well-structured, policy-dense instruction skill with a clear sequenced workflow, validation checkpoints, and concrete procedural guidance (expand-contract migrations, ownership review, deliverable templates). Its weaknesses are re-explanation of standard database concepts and a broken reference layer — most resources/*.md files cited in the body are absent from the bundle.
Suggestions
Trim guardrails that restate textbook knowledge (3NF/ACID/BASE definitions, 'measure before tuning', 'vector search is not a drop-in replacement') down to the project-specific policy they enforce, cutting token cost without losing guidance.
Fix the reference layer: the 10 cited resources/*.md files (checklist, anti-patterns, migration-playbook, query-tuning, vector-db, iso-controls, etc.) are missing from the bundle — either add them or correct the paths so navigation works.
Add an explicit validate-fix-revalidate loop for migration and query-tuning steps (e.g. 'if the migration dry-run or checklist fails, fix and re-run before delivering') to close the workflow's remaining feedback-loop gap.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and directive rather than padded, but several guardrails re-explain textbook database knowledge Claude already has: "enforce at least 3NF", "document ACID expectations explicitly", "document BASE and consistency tradeoffs", "Query tuning starts from measurement and execution plans, never guesswork", and "Never treat vector search as a drop-in replacement for lexical search". There is also redundancy between the Scheduling, Intent signature, When to use, and Expected outputs sections. This fits anchor 3 ('mostly efficient but includes some unnecessary explanation') better than anchor 4, where over-explanation would be only minor. | 3 / 5 |
Actionability | For an instruction-only skill, the guidance is largely concrete: step 2 names specific tools ("find_file, search_for_pattern, get_symbols_overview, and find_symbol"), step 7 points to "resources/anti-patterns.md §5 application ownership review", guardrail 16 specifies a full expand-contract procedure ("additive expand, dual-write + batched backfill, verified read switch, delayed contract"), and the Deliverables section enumerates concrete artifacts. It is not a 5 because actual commands are deferred to unspecified "project's migration, query, lint, or validation commands" with no illustrative examples, leaving minor gaps. | 4 / 5 |
Workflow Clarity | The 10-step canonical workflow is clearly sequenced with validation checkpoints (step 8 runs migration/query-plan/retrieval-quality commands, step 9 applies the anti-pattern review and checklist sections, step 10 notes residual risks and validation steps), plus a dedicated Failure and recovery section. It falls short of anchor 5 because there is no explicit validate-fix-revalidate feedback loop for failed migrations (the referenced resources/error-playbook.md would carry this but is not in the bundle), leaving a minor validation gap. | 4 / 5 |
Progressive Disclosure | The SKILL.md itself is a well-organized overview with a clearly labeled, one-level-deep References section (each entry annotated with its purpose, e.g. "Self-check (check the sections relevant to the task before handoff)"). However, scored against the actual bundle: 10 of the 14 referenced files under resources/ (execution-protocol.md, checklist.md, examples.md, document-templates.md, anti-patterns.md, migration-playbook.md, query-tuning.md, vector-db.md, iso-controls.md, error-playbook.md) do not exist in the bundle, so most reference navigation fails in practice. This is more than the 'minor organization gaps' of anchor 4, but the in-body structure and clearly signaled references keep it above anchor 2. | 3 / 5 |
Total | 14 / 20 Passed |