Content
78%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 tightly written, highly actionable skill body whose commands, exit codes, and routing details are copy-paste ready. Its main weaknesses are broken bundle navigation — most referenced schema and workflow files are absent from the package as shipped — and a few over-compressed conditional passages that require re-reading.
Suggestions
Ship schemas/renders.md, schemas/repo-toml.md, schemas/validators.md, and workflows/add-repository.md in the bundle (or repoint the links to files that are included) — four of the body's six reference targets currently do not resolve.
Either link references/checklist.md from the body or remove it from the bundle; an unreferenced 11 KB reference file is dead weight.
Rewrite 'A pull request changing its own review' as a numbered decision sequence (byte-identical → default-branch copy with --spec; differ → candidate copy plus warning) instead of one run-on bullet.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes competence throughout, with no explanation of concepts Claude already knows (e.g., the 'What reads what' table states facts without tutoring). Some single-sentence conditionals, like 'when they differ, the pull request upgrades the package and the default-branch checker cannot reproduce the candidate's render', cram multi-branch logic into one line and could be tightened, which keeps it below the lean anchor 5. | 4 / 5 |
Actionability | Fully executable guidance: a command block with complete paths ('.agents/skills/bot-instructions/scripts/bot-instructions render'), an explicit flag list ('--repo, --spec, --staged, --output full|local, --dry-run, --discover'), documented exit codes ('0 clean, 1 findings, 2 could not complete'), a concrete TOML surface block, and a per-bot table of exactly which files each bot reads. Copy-paste ready and covering the common cases. | 5 / 5 |
Workflow Clarity | The core flows are sequenced with validation checkpoints: 'check' re-renders and diffs with exit codes, 'adopt --dry-run' reports divergence and 'refuses symlinked targets', and the migration path is explicit ('adds it, sets [bot-instructions.bots] codex, runs adopt, then render'). Below 5 because the CI self-review workflow ('A pull request changing its own review') buries conditional branching in one run-on bullet rather than a sequenced flow with feedback loops. | 4 / 5 |
Progressive Disclosure | References are well-signaled and one level deep with precise section anchors ('schemas/renders.md § Local output', 'references/limits.md § GitHub Copilot code review'), but scoring against the actual bundle shows four of the six referenced paths — schemas/renders.md, schemas/repo-toml.md, schemas/validators.md, and workflows/add-repository.md — do not exist in the bundle, while references/checklist.md exists but is never linked. The broken navigation is a real organizational gap that the clearly-signaled style cannot offset. | 3 / 5 |
Total | 16 / 20 Passed |