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.
The body is a dense, highly actionable policy document: nearly every instruction is an exact, copy-paste-ready command with specific flags, field lists, and timing rules, and the read/write/freshness workflow is well sequenced with several explicit checkpoints. Its weaknesses are structural rather than substantive — version-sensitive Octopool routing details and metrics-interpretation guidance are inlined in a single 125-line file instead of being split into reference files, and some dense passages could be tightened.
Suggestions
Move the Octopool 0.7.1 field-routing quirks and the cache-metrics interpretation (eligible responses, route/client mix, NO_FALLBACK semantics) into a references/ file, keeping SKILL.md as a lean overview with clearly signaled links.
Place version-specific notes in an 'old patterns' or 'deprecated' section (the retired `gitcrawl gh` note is a good model) so time-sensitive details don't clutter the main path.
Tighten the multi-clause prose runs (e.g. the mergeStateStatus/comments paragraph and the proof-by-relay paragraph) into short bullet rules so each constraint is scannable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is compact and free of beginner-concept padding, but several dense prose runs (e.g. the Octopool 0.7.1 field-bundle routing passage and the cached-eligible-response metrics paragraph) could be tightened, and the inline version number 'In Octopool 0.7.1' is time-sensitive information not placed in a deprecated/old-patterns section, which the guidelines say should penalize conciseness. This fits the 'mostly efficient but includes some unnecessary explanation or could be tightened' anchor; score 4 would require trimming these passages or moving version-specific quirks aside. | 3 / 5 |
Actionability | The guidance is fully executable: exact commands with precise flags and field lists ('gh search prs "<terms>" -R owner/repo --state open --json number,title,state,url,updatedAt,isDraft,author', 'gitcrawl sync owner/repo --numbers 123 --with pr-details', 'OCTOPOOL_NO_FALLBACK=1 gh api repos/owner/repo --jq .full_name', 'octopool stats --since 24h --json'), plus concrete backoff intervals (30s/60s/120s) for CI polling. Copy-paste ready commands cover the common discovery, readback, and diagnostics cases, matching the top anchor. | 5 / 5 |
Workflow Clarity | The default path is clearly sequenced — local Gitcrawl archive first, then bare gh for current metadata, then freshness rules for when to go live — with several explicit checkpoints: 'After a write, do one targeted fresh readback', 'Check the expected head SHA and run attempt', and 'checking final current state before a maintainer action'. It falls short of the score-5 anchor because the merge/write path lacks an explicit validate-before-proceed feedback loop (gates are referenced only as things not to remove), leaving minor validation gaps. | 4 / 5 |
Progressive Disclosure | The body is well-sectioned (Default Path, Freshness, Octopool, Agent Etiquette) with no nested references, but at ~125 lines it exceeds the under-50-line simple-skill exception, and all content lives in SKILL.md with no bundle files — version-specific Octopool quirks and cache-metrics interpretation could be split into a reference file. 'Some structure but could be better organized' with inline content that could be separated fits the score-3 anchor; score 4 would require the Octopool diagnostics detail moved out or clearly partitioned. | 3 / 5 |
Total | 15 / 20 Passed |