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.
A dense, information-rich instruction skill that is highly actionable and validation-conscious, with copy-paste commands, explicit exit codes, and safety gating via markers and dry-run. Its main weaknesses are dangling references to non-existent schema/workflow files, an unreferenced checklist.md, and a few over-compressed passages that could be clearer as explicit step sequences.
Suggestions
Include the cited schemas/ (renders.md, repo-toml.md, validators.md) and workflows/add-repository.md files in the bundle, or repoint those links to files that actually ship with the skill.
Reference references/checklist.md from the body (e.g. from the 'Adding a repo' section) so every bundled file is discoverable from SKILL.md.
Rewrite the PR-self-review branching and the repo-migration path as short numbered step sequences instead of single dense conditional sentences.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is densely operational with essentially no padding — no explanations of concepts Claude already knows, and nearly every sentence carries unique rules (e.g. "render replaces only a file whose canonical marker is present; adopt is the way in"). A few convoluted passages, such as the opening paragraph on github-repository-settings selection and the byte-identical-copies CI conditions, could be tightened without losing information. | 4 / 5 |
Actionability | Concrete, executable commands are given up front (".agents/skills/bot-instructions/scripts/bot-instructions render") with flags, exit codes ("0 clean, 1 findings, 2 could not complete"), a complete TOML surface block, and specific procedures ("adds it, sets [bot-instructions.bots] codex, runs adopt, then render"). Minor gaps: the PR-CI section and manifest setup describe what to do in prose without showing the exact command invocation. | 4 / 5 |
Workflow Clarity | The render/check/adopt/retire lifecycle is clearly sequenced with real validation checkpoints: check re-renders and diffs, --staged reads the index, adopt --dry-run previews, and markers gate destructive replacement. Some multi-step workflows (the pull-request-changing-its-own-review branching, migrating a repo to the pointed doctrine) are stated in dense prose rather than as explicit step sequences, which costs the top score. | 4 / 5 |
Progressive Disclosure | References are one level deep and well signaled with section anchors, and references/limits.md exists, but the bundle does not contain the frequently cited schemas/renders.md, schemas/repo-toml.md, schemas/validators.md, or workflows/add-repository.md, so several navigation links dangle; conversely references/checklist.md exists in the bundle yet is never referenced from the body. | 3 / 5 |
Total | 15 / 20 Passed |