Content
73%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 dense, well-structured policy document: the workflow is clearly sequenced with explicit validation and destructive-operation safeguards, and references are annotated and one level deep. Its main weaknesses are redundancy across the scheduling/dependencies/guardrails sections and run-on workflow steps that could be tightened, plus an unverifiable reference set.
Suggestions
Merge "Intent signature" into "When to use" and fold the resource list in "Dependencies" into the References section to eliminate duplication.
Break the run-on workflow steps (1, 5, 6) into short imperative steps, keeping each step to a single action plus its precondition.
Consolidate overlapping guardrails (e.g. 3/4 on consistency tradeoffs, 12–15 on vector systems) or move their detail into the referenced migration/vector playbooks, keeping only the rule statement inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body mostly prescribes rather than explains known concepts (it enforces 3NF/ACID/BASE without tutorializing them), but it is noticeably redundant: "Intent signature" duplicates "When to use", "Dependencies" duplicates the References list, workflow step 7 restates guardrail 18, and steps 1, 5, and 6 are run-on sentences that could be tightened. This fits 'mostly efficient but could be tightened' better than the noticeably-padded level 2. | 3 / 5 |
Actionability | Guidance is largely executable for an instruction-only skill: named tools (Serena's find_file, search_for_pattern, get_symbols_overview, find_symbol), spelled-out procedures (expand-contract with dual-write and batched backfill; measure, explain, nominate, re-measure), and section-level pointers (anti-patterns.md §5). Minor gaps remain: no inline worked example or concrete command — those are deferred to referenced files — and several steps like "run the project's migration... commands" stay high-level. | 4 / 5 |
Workflow Clarity | The 10-step canonical workflow is clearly sequenced with explicit validation: migration commands run only after identifying the engine and tool, the checklist must be reviewed before handoff, deliverables require SQL/plan evidence and a verification outcome, guardrail 17 defines a measure-re-measure feedback loop, and the Failure-and-recovery section plus resources/error-playbook.md cover error recovery. Because this is a database skill with destructive migration risk, the presence of "verified read switch", soak windows, separate deploys for destructive steps, and "do not execute a risky migration without explicit user intent and verification" satisfies the validation requirement, so no cap applies. | 5 / 5 |
Progressive Disclosure | The References section is a model of one-level-deep, well-signaled pointers — each of the ~13 files carries a scope note (e.g. "Examples: ... (worked outputs for full design, RAG retrieval, live-table remediation...)") — and detailed material (templates, playbooks, examples) is externalized. It falls short of 5 because no bundle files are present to verify the referenced resources/*.md and ../_shared paths actually exist, the "Dependencies" section duplicates the reference list, and 18 dense guardrails inline could partly live in the referenced playbooks. | 4 / 5 |
Total | 16 / 20 Passed |