Content
78%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-engineered decision-guide skill: a clear 10-step selection workflow, concrete tool and notation defaults, and clean one-level-deep reference files confirmed to exist. It loses points for repeated routing to the same adjacent skills, abstract passages like the normalized model contract, and validation being mentioned as a deliverable rather than embedded as workflow checkpoints.
Suggestions
Consolidate the five repeated mentions of `../node-link-and-diagram-layout/SKILL.md` into one routing decision (e.g., in Overview plus the Reference Guide) and remove the duplicated mobile/workspace guidance between Core Workflow step 10, Output Expectations, and Adjacent Skills.
Make the 'normalized model contract' directive concrete with a short inline example (a 5-10 line JSON snippet showing nodes, edges, ports, and layoutHints) or point to a section in a reference file that defines it.
Add explicit validation checkpoints to the Core Workflow, e.g. a step that says to run semantic validation on the diagram source (or visual-regression fixtures for layout) and fix-and-retry before export or delivery.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, opinionated bullet guidance with no tutorial padding ('Sequence diagram: message order across actors, services, or objects'), but it is not fully lean: routing to `../node-link-and-diagram-layout/SKILL.md` is repeated five times (Overview, Core Workflow step 6, Stack Defaults, Reference Guide, Adjacent Skills), and mobile/workspace guidance recurs in Core Workflow step 10, Output Expectations, and Adjacent Skills. That repetition keeps it at 4 rather than 5; it is well above 3 because nothing explains concepts Claude already knows. | 4 / 5 |
Actionability | Guidance is concrete for a decision skill: named tools per scenario ('prefer DBML... Mermaid ER, or PlantUML IE/ER'; 'React Flow for editable node-edge UIs, Cytoscape.js for graph analysis... ELK or Dagre for auto-layout') and specific output requirements ('route foreign keys in dedicated gutters or ports; never let connectors run underneath table boxes'). It falls short of 5 because some directives stay abstract — 'Define the normalized model contract before rendering: nodes, edges, compartments, ports...' lists fields but gives no example of the contract, and there is no worked selection example showing the rules applied. | 4 / 5 |
Workflow Clarity | The Core Workflow is a coherent 10-step decision sequence from modeling job through audience, notation, format, renderer, model contract, and export/testing, with concrete sub-criteria at each step. Validation appears only as a planning item ('semantic validation, and visual regression where layout matters') rather than explicit checkpoints in the sequence, and there are no validate-then-proceed feedback loops, which keeps it below 5; the sequence is complete and well-ordered, clearly above the 3 anchor's implicit-checkpoint gap. | 4 / 5 |
Progressive Disclosure | The body is a concise overview plus decision rules, with a Reference Guide that signals exactly when to open each of five real one-level-deep files ('Read `references/formats-and-interchange.md` before reading, writing, converting, or round-tripping diagram formats'); all five referenced files exist and contain no further nested references. Cross-links to adjacent skills are peers, not nested detail. This matches the clear-overview-with-well-signaled-references anchor. | 5 / 5 |
Total | 17 / 20 Passed |