Content
56%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 an unusually rigorous governance policy with excellent validation checkpoints and mostly executable commands, but it pays for that rigor in redundancy: key rules are restated across many sections and the whole policy lives in a single monolithic file with no progressive disclosure. Tightening the repetition and splitting detailed policies into reference files would materially improve it.
Suggestions
Deduplicate the repeated non-waivable-gate lists, Factory-vs-manual restrictions, and thread-silence rules into one authoritative section that other sections reference instead of restating, which should cut the body's length substantially.
Split the detailed material into one-level-deep reference files (e.g., owner/doc exception policies, the merge gate and queue procedures, and reply-drafting rules), keeping SKILL.md as a concise decision-flow overview with clearly signaled links.
Specify the exact membership verification command (e.g., `gh api orgs/BuilderIO/memberships/<login>`) since it is required at multiple decision points, and either add `scripts/agent-friction-report.mjs` to the bundle or remove the reference to it.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~750-line body restates the same policies many times: the non-waivable-gate list ("does not waive … the ultra-scary safety gate … the independent-review requirement for PRs changing review or approval policy …") appears nearly verbatim in at least four sections, "Factory governance never merges" and the external-author approval prohibition repeat throughout, and the thread-silence rule is stated three or more times. It is not a 1 because the text is operational policy rather than explanations of concepts Claude already knows, but the padding and repetition are substantial. | 2 / 5 |
Actionability | Guidance is mostly executable with concrete commands: the paginated rulesets query (`gh api --paginate 'repos/BuilderIO/agent-native/rulesets?includes_parents=true'`), the pinned approval procedure (`event=APPROVE` and `commit_id=$reviewed_head_sha` with response verification), guarded merges (`gh pr merge <number> … --squash --admin --match-head-commit <verified-head-oid>`), the dequeue GraphQL mutation, and recap/reply templates. It is not a 5 because the repeatedly required "organization membership API" is never given as a concrete command, and `scripts/agent-friction-report.mjs` is referenced but does not exist in the bundle. | 4 / 5 |
Workflow Clarity | The pipeline (selection → author/external gates → evidence sweep → approval → readiness → merge → recap) is sequenced with exceptional validation checkpoints: membership verification, re-reading the live head before acting, verifying the returned `commit_id`, the 10-minute stable-head gate with explicit reset causes, dequeuing stale entries, and verifying the merge commit is an ancestor of `origin/main`. It is not a 5 because the Factory-vs-manual branching is scattered across roughly eight sections, so a single flow (e.g., handling a fork PR) must be reassembled from fragments. | 4 / 5 |
Progressive Disclosure | There are no bundle files at all — everything, including per-owner exception policies, merge-gate and queue procedures, and reply-drafting rules that clearly belong in separate reference files, is inlined in one 750-line SKILL.md. It is not a 2 because the section headers do provide navigable structure, matching the anchor "content that should be separate is inline"; it is not a 4 because a skill of this size should split its detailed policy material into well-signaled one-level-deep references. | 3 / 5 |
Total | 13 / 20 Passed |