Content
92%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 well-crafted procedural skill: dense, concrete, and safe, with quantified thresholds, executable commands, and explicit validation and confirmation checkpoints around a write-to-GitHub operation. The one structural weakness is progressive disclosure — it depends on a `scripts/pr-corpus.py` that is not in the provided bundle, with no inline fallback.
Suggestions
Ship `scripts/pr-corpus.py` in the skill's bundle (or verify it exists at the referenced `${CLAUDE_PLUGIN_ROOT}/scripts/` path), since Phase 2 — the voice profile that drives all drafting decisions — is unusable without it.
Add a documented scriptless fallback in §2.1 for when the script is unavailable (e.g., how to approximate the profile from `merged.json` directly), so the workflow degrades gracefully instead of stalling.
Include a brief note of the script's expected output location or schema so the profile fields referenced throughout §2–§3 (`words_by_diff_size`, `common_heading_sequence`, `no_heading_share`) can be debugged if the script's output drifts.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is ~200 lines of dense operational guidance with no explanation of concepts Claude already knows — every section carries rules, thresholds, or commands (e.g. "Fetch 100 because busy repos are often majority-bot", "conventional-commit prefix only if `conventional_share` ≥ 0.6"). The brief motivation paragraph and the "What this skill does NOT do" list are operational boundaries, not padding, so it matches the lean anchor. | 5 / 5 |
Actionability | Commands are copy-paste ready with full field lists (`gh pr view <n> --json number,title,body,...`), safe mechanics are spelled out ("body via file, never inline, so backticks/quotes/newlines survive"), and concrete thresholds govern every judgment call (buckets "small < 50 changed lines ≤ medium < 400 ≤ large", "Stay inside `p25`–`p75`"). Example dialogue lines and the sample voice read-back cover the common cases. | 5 / 5 |
Workflow Clarity | Four numbered phases with cross-referenced sections give a clear sequence, and validation checkpoints are explicit: the silent §3.3 self-check checklist before showing anything, the §4.2 confirmation gate before any write to GitHub, post-edit verification ("After editing, `gh pr view <n> --json title,body` and confirm it landed unchanged"), and an iteration loop in §4.1. The destructive/batch-operation cap doesn't apply because confirmation and verification are present. | 5 / 5 |
Progressive Disclosure | The single cross-file reference — `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/pr-corpus.py"` (§2.1) — is clearly signaled but is not present in the bundle (no `scripts/` directory exists), so the workflow's central profiling step is unusable as shipped. Structure within SKILL.md itself is good, which keeps this above a 2, but a dangling reference to the workflow's key dependency is more than the "minor organization gaps" of a 4. | 3 / 5 |
Total | 18 / 20 Passed |