Content
63%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 workflow is well sequenced with concrete commands and a useful description template, but the skill is a monolithic ~350-line file with no progressive disclosure: five full examples and duplicated anti-pattern guidance are inlined. Trimming the redundant lists, moving examples to a references file, and fixing the empty bash block in Step 5 would lift the weakest dimensions.
Suggestions
Move the five full example PR descriptions into a references/examples.md file and keep one or two condensed examples inline in SKILL.md, linking to the rest.
De-duplicate the anti-pattern guidance: 'What to Avoid' in the Description Guidelines and 'Anti-Patterns to Avoid' in Notes repeat the same four items — keep a single list.
Make Step 5 fully executable: replace the comment-only bash block with the actual write action (e.g., a concrete file-creation instruction) and add error handling for a failed `gh pr create`.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The workflow and template sections are efficient, but the body carries five full multi-section example PR descriptions (~180 lines) where two or three would convey the pattern, and the anti-pattern list is stated twice — "Empty descriptions or just issue links", "Placeholder text like 'Fixes #(issue)'", "File-by-file breakdowns" appear in both 'What to Avoid' and 'Anti-Patterns to Avoid'. This is noticeably tighter than the verbose anchor but has real padding, fitting 'mostly efficient but could be tightened' rather than 'efficient with only minor trimming'. | 3 / 5 |
Actionability | Guidance is mostly executable: concrete git commands ("git log origin/main..HEAD --stat", "gh pr create --title ... --body-file .forge/FORGE_PR_DESCRIPTION.md"), a concrete description template, and worked examples. It is not a 5 because Step 5 contains a bash block that is only a comment ("# Write the generated description to .forge/FORGE_PR_DESCRIPTION.md") with no actual command, and the write is described only in prose. | 4 / 5 |
Workflow Clarity | The six steps are clearly sequenced with a prerequisite checkpoint (verify branch is not main and has commits ahead, with explicit handling when there is nothing to create a PR for) and a final confirmation step. It misses a 5 because there is no feedback loop if `gh pr create` fails and no verification that the PR was actually created before confirming to the user. | 4 / 5 |
Progressive Disclosure | There are no bundle files (references/, scripts/, assets/ are absent), so everything — including five full example descriptions that clearly belong in an examples reference file — is inlined in a ~350-line SKILL.md. Section structure and headers are good, which keeps it above the 'minimal structure / inlined content' anchor at 2, but substantial content that should be split into separate files is inline, fitting the middle anchor rather than the well-split anchors at 4-5. | 3 / 5 |
Total | 14 / 20 Passed |