Content
81%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.
An unusually actionable, well-sequenced skill: exact commands, hard validation gates with feedback loops, and real referenced assets loaded at the right moments. Its weakness is redundancy -- duplicated guidance, two overlapping section-limit tables, and historical narrative -- that pushes the body past 300 lines when the content justifies well under 250.
Suggestions
Deduplicate the repeated '<details>' guidance, merge the 'Concision targets' ceilings table into the single 'Required body structure' table, and delete the 'A previous version of this skill incorrectly required ASCII' paragraph (keep only the current rule) -- that alone should cut 40-60 lines.
Move the multi-paragraph 'Output charset rule' rationale into an asset (or fold it into the output contract as two rules) so SKILL.md keeps only the decision, matching how mermaid gotchas are split into assets/mermaid-conventions.md.
Consolidate 'Anti-patterns flagged' and 'Gotchas' into one section; several entries ('restating the diff', 'quoting out of context') appear in both lists.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly dense, repo-specific rule-making (charset boundary, per-section ceilings, mermaid gotchas) that Claude cannot infer, but there is real duplication: 'Long verbatim quote blocks, full file listings, and full validation transcripts SHOULD live inside <details>' appears verbatim twice; the per-section ceilings table and the 'Required body structure' table restate overlapping limits; and the 'A previous version of this skill incorrectly required ASCII' paragraph is history that earns no tokens. This matches the score-3 anchor (mostly efficient but could be tightened) rather than 4, where only minor trimming would be needed. | 3 / 5 |
Actionability | Guidance is fully executable: exact input-gathering commands ('git diff --name-status <base>...HEAD', 'git log --no-merges <base>..HEAD --oneline'), a copy-paste mmdc validation loop with a real awk extraction one-liner, an exact trailer line, and a concrete drift example ('A -->|"[EXEC] work"| B'). The common case (draft a PR body, validate diagrams, self-check) is covered with commands Claude can run as written. | 5 / 5 |
Workflow Clarity | The execution checklist is a clear ordered 9-step sequence with explicit validation checkpoints and feedback loops: a lint STOP gate before drafting ('If lint is red, STOP, fix, re-run'), mandatory mermaid validation with a fix-and-rerun loop ('If mmdc reports any error, fix the diagram and re-run'), a rubric-based self-check pass, and a line-count tightening loop. This matches the score-5 anchor including error-recovery loops and a checklist. | 5 / 5 |
Progressive Disclosure | All four referenced assets (assets/pr-body-template.md, assets/mermaid-conventions.md, assets/section-rubric.md, assets/scenario-evidence-rubric.md) exist and are one level deep, each with an explicit load point tied to a step ('Load assets/mermaid-conventions.md before drafting any block'). However, the 325-line body itself carries content that belongs in those assets -- the 28-line charset rationale and the anti-patterns/gotchas overlap -- so this is good structure with minor organization gaps rather than the clean split of the score-5 anchor. | 4 / 5 |
Total | 17 / 20 Passed |