Content
75%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 highly actionable body with executable commands, a complete parameter table, and a well-sequenced workflow including explicit failure handling. The main costs are token-efficiency — the category taxonomy is repeated three times and Quick Start examples duplicate the parameter table — and a script path that does not match the actual bundle layout.
Suggestions
Collapse the triple category listing: keep the numbered Priority Categories list, and reduce Step 3 and Tips to short bullets that only add new information (emoji, table columns, review guidance) without restating category definitions.
Trim the Quick Start block to 3-4 representative invocations (default, -Category all, one filter, -OutputFormat json) since the parameter table already documents every category and platform value.
Use the bundle-relative script path 'scripts/query-reviewable-prs.ps1' in the body so the reference matches the actual bundle structure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient — a tight parameter table and executable commands — but the category taxonomy is explained three times (Priority Categories list, the Step 3 emoji list, and the Tips section: 'P/0 PRs should always be reviewed first', 'Approved PRs are ready to merge', 'Milestoned PRs have deadlines'), and the 11 Quick Start commands largely duplicate what the parameter table already specifies. Not a 2 because nothing explains concepts Claude already knows; not a 4 because the triple repetition is more than minor trimmable over-explanation. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready commands: 'pwsh .github/skills/find-reviewable-pr/scripts/query-reviewable-prs.ps1 -Category milestoned', plus a complete parameter table with values ('-Platform android, ios, windows, maccatalyst, all'), defaults, and ranges ('-Limit 1-100, default 100'). Specific examples cover the common cases; matches the 5 anchor exactly. | 5 / 5 |
Workflow Clarity | Clear three-step sequence (run script → check warnings → present all categories) with an explicit failure checkpoint: 'If the script fails... STOP - Do not attempt fallback queries... Report the error... Suggest retry', plus a concrete warning template to surface missing read:project scope. Not a 5 because there is no explicit check for empty results or guidance on verifying pwsh availability, leaving minor validation gaps. | 4 / 5 |
Progressive Disclosure | Bundle structure is one script (scripts/query-reviewable-prs.ps1) referenced consistently from the body, and the body content (parameters, workflow, categories) is appropriately placed in SKILL.md rather than inlined from elsewhere. Not a 5 because every reference uses the repo path '.github/skills/find-reviewable-pr/scripts/query-reviewable-prs.ps1' instead of the actual bundle-relative 'scripts/query-reviewable-prs.ps1' — a minor organization gap versus the actual bundle layout; not a 3 because structure and signaling are otherwise good. | 4 / 5 |
Total | 16 / 20 Passed |