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 skill: concrete commands, a verbatim report skeleton, a routing table, and validation checkpoints with an explicit recovery loop. Its weakness is token efficiency — heavy rhetorical repetition and triple-stated shape warnings — and a main file that holds more inline checklist detail than the reference split would suggest.
Suggestions
State the shape rule once and reference it: the four-heading constraint and 'edit, never rewrite' warning are fully delivered three times (Step 0, the Step 2 mid-run check, the final check); one statement plus the two command checks would cut substantial tokens.
Trim justificatory prose in Step 0 and the bullet intros (e.g. the paragraph explaining why writing the skeleton first matters) to single sentences — the imperative plus one reason is enough for a competent model.
Consider moving the JWT options subsection (the three numbered rules and their rationale) into references/checklists.md next to the Token sections it extends, keeping only the tabulation instruction inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | It never explains concepts Claude already knows and all content is repo-specific, but it is noticeably padded with rhetorical justification that could be tightened — e.g. "a run that leaves a differently-shaped file has produced nothing, however good the analysis inside it", "that is the one way this run fails outright however good the analysis is", and the shape-check warning delivered three times (Step 0, the mid-run check, the final check). Not a 2 because the padding is emphatic domain guidance rather than generic explanation. | 3 / 5 |
Actionability | Fully executable throughout: copy-paste commands ("BASE=$(git config --get branch.$(git branch --show-current).gh-merge-base || echo main)", "grep -c '^## \(Security findings\|Compliance findings\|Coverage\|Sections checked\)$' SECURITY-REVIEW.md"), a verbatim heredoc report skeleton, a grep-to-section routing table, and an exact finding template with a worked example ("**S-H1** — <short title>"). Not below 5: no pseudocode, and the common cases are covered. | 5 / 5 |
Workflow Clarity | A clearly sequenced multi-step process (Step 0 skeleton → Step 1 route the diff → Step 2 work mandatory sections → report shape) with explicit validation checkpoints and a feedback loop: the mid-run "It must print `4`. If it prints less … restore the 4 headings, put the finding back under the right one", repeated as a final check with both counts. Anti-drift: it matches anchor 5's validate-recover-checklist pattern exactly, not anchor 4 which allows missing checkpoints. | 5 / 5 |
Progressive Disclosure | References are one level deep and well signaled — "Nine more sections live in `references/checklists.md`" with all nine named, plus `references/compliance.md`, and both files exist and contain exactly those sections. Not a 5 because the main file carries ~270 lines of inline checklist bulk (Auth & Authorisation, the long JWT subsection, Cookies) that is the kind of content the rubric expects split out, even though the body justifies the split by routing frequency; not a 3 since the split that exists is deliberate and clearly navigable. | 4 / 5 |
Total | 17 / 20 Passed |