Content
52%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 skill is highly actionable — a user can create a correct agent file entirely from the templates, field specs, and mistake contrasts provided — but it is the most padded kind of document: the same examples, file-location rule, and verification guidance are repeated three to five times each. Moving the agent templates and examples into reference files and collapsing the three overlapping validation sections would cut the file by more than half with no loss of information. The stray '{{{{raw}}}}'/'{{{{/raw}}}}' markers at the top and bottom of the body also appear to be templating artifacts that should be removed.
Suggestions
Split the ~700 lines of agent templates and example agents (forge/sage/muse, plus the three near-duplicate 'Agent Templates') into a references/ directory (e.g., templates.md, examples.md) and keep only one condensed example in SKILL.md.
Merge the three overlapping validation sections ('Validation Checklist', 'Testing Your Agent', 'Verification') into a single sequential validate-then-test workflow, and state the '<cwd>/.forge/agents' location rule once in a prominent early section instead of five times.
Remove the '{{{{raw}}}}' and '{{{{/raw}}}}' templating markers that wrap the body, and drop the duplicated 'File Location' heading in the Quick Reference section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is severely padded through repetition: the file location rule is restated at least five times (including two duplicate 'File Location' headings), the forge/sage/muse example agents each appear two to three times in near-verbatim form ('Example Agent File', 'Agent Types', and 'Agent Templates' repeat the same listings), and 'Validation Checklist', 'Testing Your Agent', and 'Verification' are three overlapping validation sections. Over half of the ~1100 lines are redundant, matching the 'severely verbose; heavily padded' anchor. | 1 / 5 |
Actionability | Guidance is fully executable and copy-paste ready: complete frontmatter templates with all six required fields, field-by-field specifications, explicit bad/good contrasts for every common mistake, a validation checklist, and a concrete yamllint command for syntax checking. Not a level below (4) because the templates cover the common cases completely with no missing key details. | 5 / 5 |
Workflow Clarity | 'Creating a New Agent' gives a clear 3-step sequence (determine purpose, choose ID/title, write the file) followed by explicit validation checkpoints and testing steps. Not 5 because the checkpoints are scattered across three redundant sections (Validation Checklist, Testing Your Agent, Verification), so there is no single coherent validate-then-fix-then-retry loop; not 3 because validation is explicit and thorough despite the duplication. | 4 / 5 |
Progressive Disclosure | No bundle files exist and everything is inlined in a single ~1100-line monolith; roughly 700 lines of complete agent templates and examples clearly belong in separate reference files. Not 3 because the volume of inlined should-be-separate content far exceeds the anchor-3 example's '200 lines of API reference', and there are no references at all to signal navigation. | 2 / 5 |
Total | 12 / 20 Passed |