Content
73%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 instructional skill with an excellent clearly-sequenced workflow featuring validation and error-recovery loops, and well-signaled one-level-deep references to real bundle files. It loses points on token efficiency from repeated progressive-disclosure messaging and on actionability/organization for leaving the bundled validate-skill.ts script undocumented in SKILL.md.
Suggestions
Reference scripts/validate-skill.ts directly in the body (e.g., as a standalone validation step before packaging) so the bundled script is discoverable and actionable from SKILL.md.
Consolidate the repeated progressive-disclosure guidance — the Core Principles section, the 'Avoid duplication' bullet, and the 'Key principle' note all restate the same split-into-references advice; state it once and trim the rest.
Tighten padded sentences like the init-script description ('The script conveniently generates... making the skill creation process much more efficient and reliable') to plain statements of what the command does.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with real guidance but includes sections that could be tightened: the progressive-disclosure principle is restated at least four times (Core Principles, the Progressive Disclosure section, the 'Avoid duplication' bullet, and the 'Key principle' note), and filler like 'The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable' pads the init step. This matches anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened') — not anchor 4, where only minor trimming would be needed. | 3 / 5 |
Actionability | The body provides copy-paste-ready commands ('npx tsx <SKILL_DIR>/scripts/init-skill.ts <skill-name> --path <output-directory>', the package-skill.ts invocations), a concrete YAML frontmatter example, and worked analyses (editing-pdfs, building-frontend-apps, querying-bigquery). It falls short of anchor 5 because a bundled script, scripts/validate-skill.ts, is never referenced from the body, so a user cannot act on it from SKILL.md alone, and a few steps ('Implement changes and test again') remain high-level. | 4 / 5 |
Workflow Clarity | The six-step creation process is explicitly numbered and ordered, with per-step skip conditions ('Skip this step only when...'), an explicit validation checkpoint in packaging ('The packaging process automatically validates the skill first'), and a feedback loop for error recovery ('If validation fails... Fix any validation errors and run the packaging command again'), plus a numbered iteration workflow. This matches anchor 5 (clear sequence with explicit validation steps and feedback loops) rather than anchor 4, which allows minor validation gaps. | 5 / 5 |
Progressive Disclosure | Both real reference files (references/workflows.md, references/output-patterns.md) are one level deep and clearly signaled with when-to-read descriptions ('Multi-step processes: See references/workflows.md...'), and the body stays under its own 500-line guidance. It is anchor 4 rather than 5 because scripts/validate-skill.ts exists in the bundle but is never mentioned or navigated to from SKILL.md — a minor but real organization/discoverability gap when scored against the actual bundle structure. | 4 / 5 |
Total | 16 / 20 Passed |