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 well-structured instruction-only skill body: concrete tool-level guidance, a clearly sequenced workflow with a refine branch and verification step, and no padding. The main improvements are making verification an unconditional checkpoint and splitting the house authoring rules into a referenced file.
Suggestions
Make the step-5 verification an explicit validate→fix→retry checkpoint (always confirm folder/name match and YAML parse before reporting) instead of the hedged 'if feasible, dry-run'.
Move the house authoring rules (currently inlined from docs/skill-guidelines.md) into a references/ file, keeping a one-line summary plus a clearly signaled link in the body.
Replace or supplement the abstract Example with a short sample of the SKILL.md output it produces, so the expected artifact shape is concrete.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient and assumes Claude's competence ('Strip the one-off specifics; keep the *repeatable* shape'; 'Read enough to understand the *repeatable procedure*, not every line') with no padding or explanation of known concepts. Minor trims are possible (e.g., the parenthetical explaining what description is for, and parts of the closing Notes section), keeping it below the lean anchor. | 4 / 5 |
Actionability | Concrete, executable guidance throughout: named tools per source type (Glob/Read/Grep, WebFetch), exact paths (.claude/skills/<kebab-name>/SKILL.md), a copy-ready YAML frontmatter template, and a worked example section. Falls short of fully copy-paste-ready because the verification step is hedged ('If feasible, dry-run the procedure') and no sample authored SKILL.md output is shown. | 4 / 5 |
Workflow Clarity | Five clearly sequenced steps with an explicit refine-vs-create decision point, a clarifying-question checkpoint, and a place-and-verify step (folder/name match, YAML parses, dry-run). The refine branch has protective checkpoints ('update it in place — do not blindly overwrite'), but validation is framed as 'if feasible' rather than an explicit validate→fix→retry loop. | 4 / 5 |
Progressive Disclosure | No bundle files exist; the single ~90-line body is well organized into When to use / Workflow / Example / Notes with a small inline example. The house authoring rules inlined from docs/skill-guidelines.md are a compact summary rather than a deep reference, but the body is at the size where moving the authoring rules or the example into a references/ file would improve the split. | 4 / 5 |
Total | 16 / 20 Passed |