Content
93%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 an exemplary lean, imperative instruction set: exact commands, explicit conditions, clear before/creating sequencing, and a stop-and-ask checkpoint. The only notable gap is the absence of failure handling for the pre-flight check — what to do when `dev.py check` fails is left implicit.
Suggestions
Add one line for the failure path, e.g. "If `dev.py check` fails, fix the issues and re-run it before creating the PR" — this would close the feedback-loop gap and lift workflow_clarity from 4 to 5.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is pure imperative instruction — "Run `git log main..HEAD --oneline`", "Always `gh pr create --draft`. Push the branch first." — with zero padding and no explanations of concepts Claude already knows. The one rationale included ("GitHub renders each newline inside a paragraph as a visible line break") is non-obvious project convention and earns its tokens, matching the lean-and-efficient anchor at 5. | 5 / 5 |
Actionability | Every instruction is copy-paste ready: exact commands (`git log main..HEAD --oneline`, `uv run --no-sync dev.py check`, `gh pr create --draft`), exact file paths (`.github/pull_request_template.md`, `CHANGELOG.md`), and explicit skip conditions ("Skip if the diff does not touch Python code (`*.py`) or `pyproject.toml`"). This matches the fully-executable anchor at 5 rather than 4, where only minor gaps would remain. | 5 / 5 |
Workflow Clarity | A clear two-phase sequence ("## Before creating" → "## Creating") with a validation step (`dev.py check`) and an explicit STOP-and-ask checkpoint for multiple logical changes, matching anchor 4. It is not 5 because there is no feedback loop if `dev.py check` fails — no instruction to fix issues and re-run before creating the PR; PR creation is not destructive, so the cap-at-3 rule does not apply. | 4 / 5 |
Progressive Disclosure | The skill is under 50 lines with no need for external bundle files (no references/, scripts/, or assets/ exist), and it is organized into two well-signaled sections; the files it does mention (`.github/pull_request_template.md`, `CLAUDE.md`, `CHANGELOG.md`) are real repo files the skill must consult, not buried references. Per the simple-skill guideline this scores 5. | 5 / 5 |
Total | 19 / 20 Passed |