Content
88%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 exemplary operational playbook: executable commands with expected outputs, a validated dry-run-first workflow with rollback and failure recovery, and dense domain knowledge throughout. The main weaknesses are duplicated anti-pattern sections that could be merged and an out-of-bundle relative reference.
Suggestions
Merge the two overlapping anti-patterns sections ("Anti-patterns" and "Anti-Patterns") into one — both cover the manual_only/autopilot restriction and the fork-vs-edit guidance, so consolidating them would cut ~10 redundant lines.
Fix or inline the ../conventions/agent-operator-protocol.md reference: it points outside the skill bundle and is unverifiable from the skill's own directory, undermining the skill's self-containment.
Trim version-anchored details (e.g., the 'v0.41.22 ships' opener and the KNOBS_HASH_VERSION 5→6 note) or move them to a changelog/deprecated section so the body ages better.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly every section carries non-obvious domain knowledge (PGLite --follow requirement, apply-defaults-to-dry-run gotcha, 72h restore TTL, lock semantics) with no explanation of concepts Claude already knows. Not 5 because of real redundancy: two overlapping anti-pattern sections ("Anti-patterns" and "Anti-Patterns" both warn against running unify-types under autopilot), a decorative ASCII celebration summary, and version-specific details ("v0.41.22", "KNOBS_HASH_VERSION bump (5→6)") that could be trimmed. Not 3 because the waste is confined to a handful of lines in an otherwise lean document. | 4 / 5 |
Actionability | Fully executable throughout: copy-paste commands for every phase (gbrain schema active --json | jq, onboard --check --explain, jobs submit unify-types with the exact --params JSON including the apply:true requirement and the --follow variant for PGLite), a ready SQL rollback statement, gbrain restore/schema use revert commands, and concrete expected outputs for verification. Matches the 5 anchor: specific commands cover the common cases with the key gotchas called out. | 5 / 5 |
Workflow Clarity | A destructive batch migration (25K retypes, 5.5K soft-deletes) with a clearly sequenced 5-phase workflow and explicit validation: Phase 1 checks the active pack and expected identity string, Phase 2 mandates dry-run preview with 'if the proposed changes look wrong, don't proceed', Phase 4 lists exact expected finding transitions (pack_upgrade_available → ok, ≤16 types), plus rollback paths, failure modes with checkpoint resume, and a decision tree. Feedback loops (queued-job → resubmit with --follow, phase failure → resume from checkpoint) are present, matching the 5 anchor; the destructive-operation cap at 3 does not apply because validation is explicit. | 5 / 5 |
Progressive Disclosure | No bundle files exist, so everything is inline in one ~260-line file, but it is well-sectioned with clear headers and logical phase order rather than a wall of text. Not 5 because the body carries a relative reference outside the skill bundle ("../conventions/agent-operator-protocol.md") that is unverifiable from the skill's own directory, and content like the Output Format/Contract detail could plausibly live in a reference file. Not 3 because the structure is good and the three external Reference URLs are clearly signaled one-level-deep links. | 4 / 5 |
Total | 18 / 20 Passed |