Content
71%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 unusually dense, information-rich instruction skill: every token carries skill-specific guidance, commands are executable, and workflows carry explicit validation (exit codes, staged checks, dry-run refusals). The standout defect is navigation: most deep-dive pointers reference a schemas/ directory missing from the bundle, and the prose density makes multi-step branches harder to follow than needed.
Suggestions
Fix the dangling schemas/*.md links (schemas/renders.md, schemas/repo-toml.md, schemas/validators.md) — either ship those files in the bundle or repoint them to paths that resolve, e.g. alongside references/validators.md, which exists but is only linked via the broken schemas/ path.
Number the multi-step workflows (repo onboarding, CI check under the two-copies rule) instead of embedding them as single dense sentences, so the sequence and its branches are scannable.
Add one minimal example of a [bot-instructions] manifest TOML and one example --spec invocation, since the default-surface TOML block is currently the only concrete config example.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Dense, skill-specific prose with no padding and no explanation of concepts Claude already knows ("Exit codes: 0 clean, 1 findings, 2 could not complete"). Not 5 because the --output local rules and marker/version semantics are restated across sections and some sentences pack more clauses than needed; not 3 because nothing is unnecessary explanation. | 4 / 5 |
Actionability | Copy-paste-ready commands with full paths, a flags list, exit codes, a concrete bot-reads table, and a runnable migration sequence ("adds it, sets [bot-instructions.bots] codex, runs adopt, then render"). Not 5 because there is no example manifest TOML or example --spec invocation for common cases, and several key details defer to schemas/ files that are absent from the bundle. | 4 / 5 |
Workflow Clarity | Sequences are present with explicit validation checkpoints: exit codes, check re-render-and-diff, check --staged in the pre-commit lane, adopt --dry-run refusing symlinked targets, and the CI branch on byte-identical package copies. Not 5 because steps are embedded in dense prose rather than numbered sequences and error recovery is mostly delegated to exit codes; not 3 because validation is explicit, not missing. | 4 / 5 |
Progressive Disclosure | The design is good — one-level-deep references clearly signaled with § anchors, and references/checklist.md and references/limits.md resolve with their referenced anchors present. But 14 of 17 link targets (schemas/renders.md, schemas/repo-toml.md, schemas/validators.md) point to a schemas/ directory that does not exist in the bundle, leaving the core routing and manifest-keys details unreachable. That is more than minor organization gaps, though references are not buried and no separate-file content is inlined. | 3 / 5 |
Total | 15 / 20 Passed |