Content
81%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 exemplary orchestration skill body: fully actionable sequencing with explicit decision gates, validation checkpoints, resumability, and error-recovery loops, with heavy detail correctly pushed into two real reference files. The main cost is token efficiency — substantial boilerplate repetition inflates length without adding guidance value.
Suggestions
State the agent model-dispatch convention (`.arness/agent-models/code.md` plus the ensure-config fallback) once in an early 'Agent dispatch' note and reference it from Steps 3 and 11 instead of repeating the full parenthetical four times.
Replace the ten inline progress-display code blocks with one template plus a stage order list (scope → assess → ... → ship) and instruct per step: "Show progress with the current stage highlighted."
Consider moving the per-gate AskUserQuestion wording and options for G1-G7 into a decision-gates section of a reference file, keeping the compact gate table in the main body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient prose with no explanations of concepts Claude already knows, but it repeats the agent-dispatch parenthetical ("passing the model from `.arness/agent-models/code.md` as the `model` parameter... Dispatch convention for fallback") four times, inlines ten near-identical progress-display code blocks, and duplicates the pattern-file list in both Prerequisites and Step 0. It matches anchor 3 (could be tightened) rather than 2, since the padding is repetitive boilerplate rather than unnecessary explanation. | 3 / 5 |
Actionability | Every step gives executable guidance: exact gate questions and options, exact invocations (`Skill: arn-code:arn-code-plan <spec-name>`, Agent tool with model parameter and fallback reference), artifact filename patterns (`ASSESSMENT_<scope-name>.md`, `spec_states` tracking), and explicit Read commands for the protocol references. Nothing is left as vague direction, matching anchor 5; anchor 4 would require missing key details, and there are none. | 5 / 5 |
Workflow Clarity | The multi-step pipeline is explicitly sequenced (Steps 0-13) with seven named decision gates, a resumability artifact table, per-spec conflict detection before execution, and a test-verdict feedback loop ("Fix and re-test... Loop on option 1 until tests pass"). As a batch operation across multiple specs it has explicit validation checkpoints and error-recovery branches throughout, matching anchor 5. | 5 / 5 |
Progressive Disclosure | Two real, one-level-deep references (`references/assessment-protocol.md`, `references/orchestration-flow.md`) are loaded at point of need with explicit Read commands, and detail-heavy material (agent prompt templates, merge/dedup procedures, ordering heuristic) is properly externalized. It falls short of anchor 5 because the body still retains inline detail that could be externalized — per-gate question scripts, the repeated dispatch convention, and the ten progress-display blocks — and it leans on a cross-skill reference for the dispatch fallback. | 4 / 5 |
Total | 17 / 20 Passed |