Content
96%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.
An exceptionally tight operational protocol: every step is a command, a gate, or a recordable output, with validation and escalation paths explicit at each risky point. The only structural weakness is that the referenced context files are not present in the skill bundle and use project-root-relative rather than skill-relative paths.
Suggestions
Ship the three reference files (loop-engineering.md, step-contracts.md, workflow-definition.md) inside the skill's own references/ directory so the References section resolves when the skill is installed standalone.
Use bundle-relative paths (e.g., references/loop-engineering.md) instead of skills/flow-driven/references/... so the pointers survive being copied out of the source repo.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and directive throughout — commands like `flow_lint.py <ws>`, `flow_board.py <ws>`, `flow_next.py <ws>`, exact fields (`step`, `step_entered`, `holder`, `evidence_exits_met`), and exact report strings (`CYCLE-COMPLETE <rule> <slug>`). It never explains concepts Claude already knows; even the rhetorical one-liners ('a recorded "we could not" beats an invented "we did"') encode behavioral rules rather than padding. Not score 4 because there is no over-explanation to trim — every sentence changes what the agent does. | 5 / 5 |
Actionability | Fully executable for an instruction-only skill: concrete commands with exit-code semantics ('Exit code 4 means the top move is a human decision'), exact file destinations (`reviews/loop-log.md`, `improvements/`, `learnings/`), exact fields to update, and explicit handling of the common cases (lint failure, wrong card, no declared verification, blocked item, over-WIP). Per the scoring notes, absence of code is not penalized when guidance is this actionable. Not score 4 because there are no missing key details the body itself owes — the contract-specific details are correctly delegated to the run card. | 5 / 5 |
Workflow Clarity | The 9-step workflow has an explicit validation gate ('GATE: violations mean... fixing them is this cycle's move, and nothing else is'), an independent verification step with a skeptic's brief, error-recovery paths (escalation, back-edge, DECISION-PENDING), a re-projection step ('Re-run `flow_board.py` (it appends the transition)'), and a closing Quality Gates checklist. Not score 4 because validation checkpoints are explicit at every risky point, not implicit. | 5 / 5 |
Progressive Disclosure | The References section is clearly signaled and one level deep, with a one-line purpose per file ('the six beats and why the leverage table is ordered the way it is'). However, the referenced paths (`skills/flow-driven/references/loop-engineering.md`, `step-contracts.md`, `workflow-definition.md`) are repo-root-relative and the bundle contains no `references/` directory, so the targets cannot be verified as real files and would not resolve if the skill were installed alone. Not score 5 because a well-signaled reference section only earns the top anchor when the referenced files are actually part of the bundle; not score 3 because the SKILL.md itself is a proper overview with nothing inlined that belongs in a separate file. | 4 / 5 |
Total | 19 / 20 Passed |