Content
86%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 body is a well-structured overview: token-efficient tables, a sound creation workflow with validation, edge-case decision rules, and a clean one-level reference layout. The main weakness is that file-creation guidance leans on the references for concrete templates, leaving a few minor gaps in the main workflow.
Suggestions
In 'Step 3: Create the File', inline one minimal frontmatter template (e.g., a two-line SKILL.md header) so the most common case is executable without loading a reference file.
Strengthen 'Step 4: Validate' with an error-recovery branch (e.g., 'if frontmatter fails to parse, check for unescaped colons/tabs and re-check') to close the feedback loop.
Add a line in the Quick Reference section covering common natural-language triggers (slash commands, chat modes) to align the body's trigger guidance with the description's USE FOR list.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Lean and efficient: dense decision-flow and location tables, no concept explanations Claude already knows, no padding — every section (Decision Flow, Quick Reference, Creation Process, Edge Cases, Common Pitfalls) adds non-obvious discriminating knowledge. Matches the 'every token earns its place' anchor. | 5 / 5 |
Actionability | Mostly concrete, executable guidance: exact paths (.github/instructions/, {{VSCODE_USER_PROMPTS_FOLDER}}/), specific rules ('Always quote descriptions that contain colons', avoid applyTo: "**"), and per-primitive reference links. Not 5: step 3 ('Include required frontmatter as needed', 'Add the body content following the templates') is loose and defers all templates/examples to references without inline minimal examples; not 3: what is written is specific and directly actionable. | 4 / 5 |
Workflow Clarity | Clear four-step sequence (Determine Scope → Choose Primitive → Create File → Validate) with an explicit validation step (correct location, YAML frontmatter syntax, description present). Not 5: validation is a light checklist without feedback-loop detail (what to do on failure, how to verify syntax mechanically); not 3: the sequence and checkpoints are explicitly present, and no destructive/batch operations apply the cap. | 4 / 5 |
Progressive Disclosure | Clear overview in SKILL.md with well-signaled, one-level-deep references: all six linked files (agent-instructions.md, instructions.md, prompts.md, hooks.md, agents.md, skills.md) exist, are organized per primitive in a navigation table, and contain no further nested references. Matches the 'clear overview with well-signaled one-level-deep references' anchor. | 5 / 5 |
Total | 18 / 20 Passed |