Content
73%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-structured, highly actionable workflow with explicit validation gates and error-recovery loops, and no bundle-file bloat. Its main cost is redundancy: the push-failure policy appears in three places (Steps, Commands comments, Notes) and Goals duplicates the description, which inflates token usage without adding guidance.
Suggestions
Consolidate the push-failure policy into one place — keep the decision tree in step 4 and reduce the Notes section to a one-line pointer ("sync problems → `pull` skill; auth/permission errors → surface and stop") instead of restating it.
Drop or shrink the Goals section (it restates the frontmatter description) and fold Prerequisites into a single line, saving tokens without losing guidance.
Consider moving the repo-specific backend/frontend validation command blocks into a referenced file (e.g. references/validation.md) so the Commands section stays focused on the push/PR flow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body triple-states the push-failure policy — in step 4 ("If push is not clean/rejected... run the `pull` skill... surface the exact error"), again as comments in the Commands block, and again in Notes ("Distinguish sync problems from remote auth/permission problems") — and the Goals section restates the frontmatter description. Not a 2 because there is no padding or explanation of concepts Claude already knows; not a 4 because the redundancy across Steps/Commands/Notes is more than a minor trim. | 3 / 5 |
Actionability | The Commands section is largely executable: concrete validation gates ("ruff check app tests", "pytest tests/unit -v", "npm run typecheck"), "git push -u origin HEAD", and gh pr commands. Not a 5 because the PR-body writing path is only a commented example workflow ("open the template and draft body content") and `pr_title` is a placeholder rather than copy-paste-ready; not a 3 because nearly everything else is runnable as written. | 4 / 5 |
Workflow Clarity | Steps 1-8 are clearly sequenced with explicit validation checkpoints (pre-push validation gates, step 7's placeholder check "rg -n '<!--|Fixes #$|TODO|TBD'") and a feedback loop for error recovery (rejected push → `pull` skill → re-validate → retry). Matches the 5 anchor; the 4 anchor's 'minor validation gaps' does not apply since both push and PR-body validation are explicit. | 5 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent), and the single body is well-organized into Prerequisites/Goals/Related Skills/Steps/Commands/Notes with clear navigation. Not a 5 because at ~126 lines it exceeds the under-50-line simple-skill case and the repo-specific validation command block is long enough that it could live in a referenced file; not a 3 because structure is clean and nothing is buried. | 4 / 5 |
Total | 16 / 20 Passed |