Content
83%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 well-crafted, token-efficient reference: concrete templates, examples, and naming conventions with essentially no padding, and excellent copy-paste-ready frontmatter guidance. Its weakest area is workflow clarity — the authoring process is conveyed through well-ordered sections rather than an explicit step sequence with validation checkpoints — and progressive disclosure relies entirely on inline sections with no reference files. Both are reasonable choices at this scale but leave room for a more procedural, checkpoint-driven layout.
Suggestions
Add a numbered "Creating a skill" procedure that sequences the existing sections into explicit steps (1. decide skill vs AGENTS.md, 2. create the directory and frontmatter from the template, 3. write the description using the checklist, 4. add the `$skill-name` pointer to AGENTS.md), so the implicit section order becomes an explicit workflow.
Include a validation checkpoint at the end of the creation workflow, e.g. re-read the description and confirm it names the trigger scenario and key file names, or verify the frontmatter contains only supported fields — closing the checkpoint gap that currently caps workflow clarity.
If the skill grows beyond its current size (e.g. adding a full worked SKILL.md example), move the description-writing guide and content conventions into a reference file (e.g. writing-descriptions.md) referenced one level deep from SKILL.md, exercising the hub + detail pattern the skill itself teaches.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is a lean reference of repo-specific conventions — the supported-frontmatter field table, good/bad description examples, naming rules, and the AGENTS.md-vs-skill comparison table — with no explanation of concepts Claude already knows. Every section carries non-obvious prescriptive information ("Only use fields from this list. Unknown fields are silently ignored.", "No repo prefix (already scoped by `.agents/skills/`)"), matching the anchor for every token earning its place. At most the two file-tree diagrams trivially overlap, which is not enough to drop to anchor 4's "minor instances of over-explanation". | 5 / 5 |
Actionability | For an instruction-only skill, the guidance is fully actionable and copy-paste ready: a complete frontmatter template with per-field semantics ("argument-hint: '<pr-number>' # Optional. Hint for expected arguments."), concrete good/bad description examples ("description: Helps with flags." vs the good multi-line form), explicit naming rules ("Hyphens for multi-word names"), and the hub + detail file pattern. These cover the common case — creating a new skill — end to end. The one gap is that no full worked example of a finished SKILL.md body is shown, but the pieces provided are executable as-is, so this sits at anchor 5 rather than 4. | 5 / 5 |
Workflow Clarity | Sections are logically ordered (when to create → file structure → frontmatter → description writing → content conventions → naming), but the sequence is only implicit: there is no explicit step-by-step authoring procedure and no validation checkpoints (e.g. a step to verify the new skill triggers or that the frontmatter parses). This matches anchor 3 ("sequence present but checkpoints missing or implicit") rather than anchor 4, which requires most checkpoints to be present. It is above anchor 2 because the organization is coherent with few gaps, and the skill involves no destructive or batch operations, so the workflow-clarity cap does not apply. | 3 / 5 |
Progressive Disclosure | The body has good structure with clear, well-scoped sections and appropriately sized inline content (~104 lines), and it models the hub + detail pattern for other skills (workflow.md, local-repro.md). No bundle files exist (references/, scripts/, assets/ are absent), so everything is inline — appropriate at this size but without any actual one-level-deep reference split, which is what anchor 5 rewards. This places it at anchor 4 (good structure, minor organization gaps) rather than 5; not 3, since no content that clearly belongs in a separate file is inlined and navigation is easy. | 4 / 5 |
Total | 17 / 20 Passed |