Content
78%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 exceptionally lean and mostly actionable, with a clear run sequence and user-facing checkpoints. Its main weakness is that the referenced workflow.py — the skill's entire engine — is absent from the bundle, which weakens both actionability and navigation, and there is no error-recovery guidance for failure cases.
Suggestions
Ship workflow.py in the bundle (e.g., alongside SKILL.md or in scripts/) so the referenced script actually exists — the skill cannot run without it, and the body instructs editing constants in it.
Add brief error-recovery guidance for likely failure modes: no changed files found, merge-base with origin/develop unavailable, or run_workflow failing mid-run.
Clarify the checkout responsibilities: step 1 says to check out the target while the overview says reviewers check out HEAD from origin — state explicitly who checks out what and when to avoid duplicated or conflicting checkouts.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~37-line body is lean and operational throughout — constants with defaults, exact commands ("git -C <REPO_DIR> fetch origin"), output markers ("FINAL_MARKDOWN_BEGIN" / "FINAL_MARKDOWN_END"), and no explanations of concepts Claude already knows. Every token earns its place, matching the 5 anchor; not 4 because there is no over-explanation to trim. | 5 / 5 |
Actionability | Concrete, near copy-paste guidance: "run_workflow(workflow_name=\"review-contributing-design\", script_path=<path to workflow.py>)", "cp workflow.py ~/workflows/review.py", and constant names with defaults (HEAD_REF, BASE_REF, REPO_DIR). Falls short of the fully-executable 5 anchor because the entire skill depends on "workflow.py (next to this file)", which is not present in the bundle — a missing key artifact rather than a minor gap, but above the incomplete/pseudocode level of 3. | 4 / 5 |
Workflow Clarity | Clear sequenced steps (fetch → check out → run_workflow → extract between FINAL_MARKDOWN_* markers → save and attach) with checkpoints: "Tell the user how many files that is before starting a wide range" and "Spot-check one or two findings before reporting" — validation is present, so the batch-operation cap does not apply. Not the 5 anchor because there is no error-recovery guidance (e.g., empty diff, failed merge-base, run_workflow failure); clearly above the 3 anchor's implicit checkpoints. | 4 / 5 |
Progressive Disclosure | Sections are well organized and the reference to workflow.py is one level deep and clearly signaled, but the referenced file does not exist in the bundle (no references/, scripts/, assets/, or workflow.py alongside SKILL.md), leaving a dangling reference that breaks navigation. The under-50-lines no-external-references exception does not apply since the skill's main payload lives in the missing file; this sits between the good-structure 4 anchor and the buried/inline-content 2 anchor, matching the 3 anchor's imperfect reference organization. | 3 / 5 |
Total | 16 / 20 Passed |