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 body is highly actionable with complete, executable examples and solid validation guidance, but it is roughly 3-4x longer than needed due to heavy internal repetition, and it inlines large example/template catalogues that should live in separate reference files. Deduplicating and splitting the content would substantially raise quality.
Suggestions
Deduplicate aggressively: the 'check' example appears three times and the 'forge list' verification instructions verbatim twice — keep each item in exactly one section and cross-reference it elsewhere.
Move the examples library, the four command templates, and the 'Common Mistakes to Avoid' catalogue into a references/ file (e.g., references/examples.md), keeping SKILL.md as a concise overview with clearly signaled one-level-deep links.
Consolidate 'Validation Checklist', 'Testing Your Command', and 'Verification' into a single validation section with one ordered workflow, removing repeated naming/tag guidance that already appears under 'Best Practices' and 'Quick Reference'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~710-line body is heavily padded with repetition: the identical 'check' command example appears three times, the 'forge list command' verification block is duplicated verbatim, naming rules appear in three separate sections, and the file-location warning is restated four times. It also restates basics Claude already knows ('Start with an action verb', 'Be specific and actionable'), fitting anchor 2 ('Noticeably verbose; several unnecessary explanations or padded sections'); it is not anchor 1 because it rarely explains generic external concepts, just its own content repeatedly. | 2 / 5 |
Actionability | Everything is executable: complete example command files with real frontmatter, exact directory paths ('<cwd>/.forge/commands'), runnable tag commands ('cargo +nightly fmt --all...'), and copy-paste verification commands ('forge list command --custom', 'yamllint path/to/your-command.md'). This matches anchor 5's 'Fully executable; copy-paste ready code or commands; specific examples cover the common cases'. | 5 / 5 |
Workflow Clarity | A clear sequence exists ('Step 1: Determine Command Purpose' through 'Step 3: Write the Command File', followed by testing and forge-recognition verification) with an explicit validation checklist and an error-recovery loop ('If your command doesn't appear in the list, check: file location...'). It falls short of anchor 5 because the workflow is fragmented across three overlapping sections ('Validation Checklist', 'Testing Your Command', 'Verification') rather than one coherent flow, but it exceeds anchor 3's 'checkpoints missing or implicit'. | 4 / 5 |
Progressive Disclosure | The body has good section headers but is a 710-line monolith with no bundle files at all: the examples library, four templates, the common-mistakes catalogue, and the quick reference clearly belong in separate reference files. This matches anchor 3 ('Some structure but could be better organized... content that should be separate is inline'); it is above anchor 2 because headers make it navigable, and below anchor 4 because nothing is split out. | 3 / 5 |
Total | 14 / 20 Passed |