Content
75%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.
The body is highly actionable, with executable gh commands, complete examples, exact labels, and clearly sequenced workflows that include verification for risky label operations. Its weaknesses are redundancy — the evidence/approval rules and auto-label mappings are repeated across three or more sections — and the absence of any progressive-disclosure structure, with all template details inlined in a single file.
Suggestions
State the proportional-evidence and status:approved rules once (e.g., in Critical Rules or a short CONTRIBUTING.md pointer) and have the Workflow, Maintainer Approval Workflow, and Label System sections reference them instead of restating them.
Collapse the per-template "Auto-labels" lines and the "Applied Automatically on Issue Creation" table into one source of truth for the label mapping.
Move the full CLI example bodies and the per-template required/optional field tables into a references/ file (e.g. references/templates.md), keeping SKILL.md as the overview with clearly signaled one-level-deep links.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body avoids concept fluff but restates the same rules multiple times: proportional-evidence/status:approved rules appear in Critical Rules ("maintainer-accepted proportional evidence... current-main reproduction and root cause"), again in Workflow steps 5–6, and again in Maintainer Approval Workflow step 4; auto-labels are listed per-template and duplicated in the Label System table. This is more than the minor trimmable instances of anchor 4, fitting anchor 3's "could be tightened". | 3 / 5 |
Actionability | Guidance is fully executable: complete `gh issue create` commands with full example bodies for bug and feature templates, exact template paths (`.github/ISSUE_TEMPLATE/bug_report.yml`), exact label names, and a copy-paste-ready status-replacement script including jq filtering and error handling. This matches anchor 5's "fully executable; specific examples cover the common cases". | 5 / 5 |
Workflow Clarity | Workflow and Maintainer Approval Workflow are clearly sequenced, and risky label/closure operations include validation: the status-replacement script verifies the result and exits on failure ("status replacement could not be confirmed; stop without retrying"), and bug approval requires reproducing against "exact current remote main and record SHA". It falls short of anchor 5 because several checkpoints remain implicit (e.g., what triaging involves, when to close vs. explain) with no recovery guidance beyond the one script. | 4 / 5 |
Progressive Disclosure | With no bundle files, the ~250-line body is a single well-sectioned file with clear headers (templates, labels, workflows, decision tree, commands) that is easy to navigate, and the one external reference ("../../docs/contribution-policy-transition.md") is clearly signaled and explicitly flagged as not active. It is not anchor 5 because there is no reference structure at all — the four template field tables and worked examples could be split into one-level-deep reference files to slim the main file. | 4 / 5 |
Total | 16 / 20 Passed |