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-organized, opinionated instruction skill with concrete file targets, config keys, a linter checkpoint, and quality gates. The main gaps are an implicit (never explicit) validate-and-fix loop, no shown linter invocation or inline contract example, and inconsistent reference paths with template/linter files missing from the bundle and the References list.
Suggestions
Make the validation loop explicit in the Workflow section: after running flow_lint.py, add 'fix violations and re-run until zero' with the actual command invocation (e.g., 'python scripts/flow_lint.py workflow.md').
Harmonize reference paths — use one consistent prefix (either 'references/discovery-interview.md' or 'skills/flow-driven/references/discovery-interview.md') and give 'workflow-archetypes.md' its full path in the body.
Add templates/workflow.md, templates/step.md, and flow_lint.py to the References section (and ensure they exist in the bundle), and include one minimal inline example of a step contract (intent, exit_evidence, rung, run, escalation) so the deliverable shape is visible without opening the template.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and directive with almost no explanation of concepts Claude already knows; each section carries actionable guidance (path table, nine moves, rules with rationale). A few rhetorical asides could be trimmed — the STATIK provenance note ('which STATIK never had to') and flourishes like 'This move produces more argument than the other eight combined, which is the point' — keeping it at anchor 4 rather than the fully lean anchor 5. | 4 / 5 |
Actionability | Guidance is concrete for an instruction-only skill: specific output files ('reviews/YYYY-MM-DD-workflow-discovery.md', 'steps/<id>.md'), config keys ('unit', 'unit_outcome', 'evidence_exits', 'decision_points'), a rung scale, and a linter ('flow_lint.py'). Minor gaps keep it below anchor 5: no invocation for flow_lint.py is shown, and there is no inline example of a step contract or workflow.md fragment — everything is delegated to template/reference files. | 4 / 5 |
Workflow Clarity | The Workflow section gives a clear nine-step sequence with a validation checkpoint (step 8: run flow_lint.py and treat violations as design problems) and a Quality Gates checklist. The error-recovery loop (fix violations and re-run the linter) is implied but never explicit, and the linter is referenced without a command, fitting anchor 4 rather than the explicit feedback-loop anchor 5. | 4 / 5 |
Progressive Disclosure | Structure is good: an overview body with an annotated, one-level-deep References section covering interview, first-principles, unit-of-value, schema, contracts, and archetypes files. Minor organization gaps: the body and the References section use inconsistent paths ('references/discovery-interview.md' vs 'skills/flow-driven/references/discovery-interview.md', bare 'workflow-archetypes.md'), and referenced files (templates/workflow.md, templates/step.md, flow_lint.py) are neither listed in References nor present in the bundle — anchor 4 rather than 5. | 4 / 5 |
Total | 16 / 20 Passed |