Content
88%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 instruction skill: the body sticks to non-obvious MCP behaviors (auto-derived identifiers, empty-steps create, full-replace PUT semantics, tool-result verification) and delegates step-building mechanics to real, one-level-deep reference files, with explicit validation checkpoints around the destructive update path. Weaknesses are minor: a slightly over-explained YAML conventions paragraph with some repetition between Performance Notes and Troubleshooting, and a scope-establishment reference whose path escapes the skill bundle and is absent from references/.
Suggestions
Tighten the YAML Output Conventions paragraph to a one-line rule (e.g., 'Emit block-style YAML only; the JSON-shaped examples in components.md are authoritative for structure, never for output format') and drop the duplicated full-replace PUT sentence from Performance Notes or Troubleshooting so it lives in one place.
Fix the scope-establishment reference: either copy scope-establishment.md into the skill's own references/ directory and link it relatively (references/scope-establishment.md) or inline the four scope bullets once, since the ../../../ path is absent from the bundle and fragile if the skill is moved.
Reduce the repeated '(pass org_id/project_id using the active scope)' parenthetical by stating once in Scope Rules that all MCP calls in this skill inherit the active scope.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and procedural throughout — field-by-field scaffold annotations ('auto: <identifier>_pipeline, does NOT change'), the full-replace PUT warning, and the intent keyword table all carry non-obvious Harness-specific knowledge with no 'what is chaos engineering' padding. A few spots could be trimmed: the YAML Output Conventions paragraph over-explains ('appear as minified JSON purely for token efficiency — JSON parses identically to YAML...'), the '(pass org_id/project_id using the active scope...)' parenthetical repeats, and the full-replace PUT point appears in both Performance Notes and Troubleshooting. That matches anchor 4 (efficient, minor over-explanation) rather than anchor 5. | 4 / 5 |
Actionability | The body gives copy-paste-ready MCP call templates with full parameters ('harness_create(resource_type="chaos_dr_test", org_id="<org_id>", project_id="<project_id>", body={"name": "...", "identifier": "..."})'), a complete annotated YAML scaffold, an exact naming-convention derivation, and concrete example utterances routed to files. Specific examples cover the common create/edit/query cases, matching anchor 5. | 5 / 5 |
Workflow Clarity | The flow is clearly sequenced: Step 0 intent detection (with a keyword table and explicit ambiguous fallback question) routes to create.md/edit.md, which hand off to components.md, with a defined save path and loop-back hubs. Despite full-replace PUT being a destructive operation, validation is explicit — 'NEVER claim a tool call succeeded without an explicit success response', 'Wait for the tool's confirmed response before reporting success; a review/elicitation prompt is not a completed save' — with feedback loops (retry on ambiguous response) and error-recovery guidance in Troubleshooting ('always harness_get the current YAML immediately before modifying'). This matches anchor 5 and avoids the destructive-operation cap at 3. | 5 / 5 |
Progressive Disclosure | SKILL.md is a genuine overview that routes to one-level-deep, well-signaled references with purpose statements ('read references/create.md — creates a brand-new DR Test pipeline...'), and all three referenced bundle files (components.md, create.md, edit.md) exist with sensible cross-links. However, the body's first reference — 'Follow references/scope-establishment.md (../../../references/scope-establishment.md)' — points outside the bundle and the file is not present in references/, a dangling path from the bundle's perspective. Good structure with a minor navigation gap matches anchor 4 rather than 5. | 4 / 5 |
Total | 18 / 20 Passed |