Content
88%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 strong, highly actionable single-file skill: exact gh/git/python commands, a well-sequenced workflow with validation and a transient-UNKNOWN re-check loop, and clean one-level references to the repo's own source-of-truth files. The only real costs are a duplicated review-output section and an inlined copy of the submission contract that the referenced files already define.
Suggestions
Merge the overlapping "### 6. Produce the review" and "## Output Shape" sections into one, since both specify findings-first/severity-ordering and the decision fields.
In "### 2. Validate the submission contract", replace the full inlined contract list with only the deltas and edge cases (e.g., source vs source_link, the docs/index.md symlink) and defer the rest to CONTRIBUTING.md/TEMPLATE.md, which are already listed as sources of truth.
In the repair workflow, add an explicit pre-push validation step (re-run scripts/pattern_validator.py on the repaired file) before the force-push to the contributor's branch.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with repo-specific rules Claude cannot know ("source_link is invalid here; use source", "docs/index.md is only a compatibility symlink", "One pattern per PR") and wastes no tokens teaching general concepts. It falls short of 5 because section 6 ("Produce the review") and "Output Shape" both specify findings-first/severity-ordering, a duplication that could be merged into one section. | 4 / 5 |
Actionability | Guidance is copy-paste ready: exact `gh pr view` invocation with the full --json field list, `gh pr diff --patch`, the `git fetch origin refs/pull/<number>/head:pr-<number>` refspec, `python3 scripts/pattern_validator.py --all`, `bun run build:data`, and push with `--force-with-lease`. Not 4 because the commands are complete and cover the common review paths. | 5 / 5 |
Workflow Clarity | The 6-step workflow has an explicit sequence with validation checkpoints and feedback loops: run `lint_front_matter.py` / `pattern_validator.py` as structural checks, re-check `gh pr view` after pushing because "`mergeable` and `mergeStateStatus` may temporarily show `UNKNOWN`", and treat scripts as checks with human review as decision-maker. The destructive force-push step includes the safety mechanism and post-push re-validation, matching the 5 anchor. | 5 / 5 |
Progressive Disclosure | A "Read First" section clearly signals one-level-deep references to real repo files (`CONTRIBUTING.md`, `TEMPLATE.md`, `scripts/lint_front_matter.py`, `scripts/pattern_validator.py`, `scripts/build-data.ts`) and instructs quoting repo rules rather than restating from memory. Not 5 because section 2 then inlines the full submission contract that CONTRIBUTING.md/TEMPLATE.md already hold — content that could be trimmed to deltas or deferred to the referenced source of truth. | 4 / 5 |
Total | 18 / 20 Passed |