Content
80%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-organized, product-dense instruction body that gives exact paths, schemas, and procedures with almost no padding. Its main weakness is the absence of validation/verification checkpoints — most notably around the destructive delete workflow, which caps workflow clarity.
Suggestions
Add a validation checkpoint to destructive operations: before deleting, confirm the exact skill name and scope with the user (or verify the directory matches the requested skill) since 'remove the whole skill directory' is unrecoverable.
Add a post-write verification step for create/update, e.g. re-check that the frontmatter name matches ^[a-z0-9]+(-[a-z0-9]+)*$, the directory name matches the frontmatter name, and the description is within 1–1024 chars.
Trim the minor redundancy between the 'Where skills live' scope paragraph and the Create bullet, and drop the 'it is bewildering' justification to tighten conciseness.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with product-specific facts Claude cannot know (discovery order, frontmatter schema with regex and char limits, precedence rules) and avoids re-teaching known concepts, but has minor trimmable instances such as justifying the one-question rule ('it is bewildering') and near-duplicate scope guidance in two sections ('Choose the scope before writing... Ask the user which they want...' vs the Create bullet), matching the 'efficient with minor over-explanation' anchor rather than the every-token-earns-its-place anchor. | 4 / 5 |
Actionability | Guidance is fully executable for an instruction-only skill: a copy-paste-ready SKILL.md template, exact directory paths per scope, the precise name regex and length limits, and per-operation procedures (create/update/delete). Anchor 4 ('minor gaps') does not apply — nothing a reader needs to act is left abstract. | 5 / 5 |
Workflow Clarity | The requirement-gathering sequence is clear (ordered questions, skip answered ones, then scope then write), but validation checkpoints are absent throughout: the destructive delete operation ('remove the whole skill directory') has no confirm-before-delete or name-target verification step, and create/update have no post-write check that the frontmatter is valid. Per the rubric, a destructive workflow without validation is capped at 3; it is not a 2 because steps are concrete and correctly sequenced, not gapped. | 3 / 5 |
Progressive Disclosure | This is a single-file skill (~110 lines) with no bundle files, and nothing is inlined that clearly belongs in a separate file; headers (Gathering requirements, What a skill is, Where skills live, SKILL.md format, Support files, Create/update/delete, Applying changes) make navigation trivial, which matches the simple-skill exception for well-organized single-file skills. | 5 / 5 |
Total | 17 / 20 Passed |