Content
71%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-structured, genuinely actionable instruction-only skill: the survey procedure, finding heuristics, demolition test, and report contract are all concrete enough to execute, and the section organization is clean with an explicit completion definition. Its main cost is sustained nautical metaphor that decorates nearly every section without adding instruction, and the absence of a single worked example keeps the report format one step short of fully unambiguous.
Suggestions
Cut or reduce the decorative metaphor ("charts the reef", "the yard's busy water", "reads one card, not the whole reef", "simply sinks") — it appears in almost every section and adds tokens without adding instruction.
Add one short worked example of a candidate card (evidence file:line, deepening move, risk note, severity/confidence/actionable labels) so the report contract is unambiguous on first use.
State the commit-history weighting step in plain operational terms ("read recent commit history and focus on the most-edited areas") rather than as an extended metaphor.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The instructional content itself is lean and assumes competence — finding definitions, the demolition test, and report structure are all stated without padding — but decorative nautical metaphor is sprinkled throughout ("A surveyor charts the reef; the captain decides whether to dredge", "weight the walk toward the yard's busy water", "the captain reads one card, not the whole reef", "it simply sinks"), and each instance costs tokens without adding instruction. Not a 2 because no section explains concepts Claude already knows and the body is short; not a 4 because the metaphorical padding recurs in nearly every section and could be cut. | 3 / 5 |
Actionability | The guidance is concretely executable for an instruction-only skill: a three-step procedure, mechanically checkable heuristics ("a boundary crossed by exactly one adapter with no second caller; checkable by counting callers"), a falsifiable demolition test applied to every suspect, and a fully specified report format (evidence at file:line, one-sentence deepening move, risk note, top recommendation). Not a 5 because there is no worked example of a finding or a sample candidate card, which would make the report contract unambiguous. | 4 / 5 |
Workflow Clarity | The sequence is clear and ordered: read principles and seam vocabulary → walk the module graph (with an explicit weighting rule via commit history) → classify findings → apply the demolition test filter → rank by leverage against risk → report → handoff. The demolition test acts as a per-suspect checkpoint and the completion definition ("report exists with evidence, rankings, and risk notes — and no file was modified") is an explicit end-state check. Not a 5 because there are no feedback loops or mid-survey error-recovery steps, though the skill is non-destructive so the validation cap does not apply. | 4 / 5 |
Progressive Disclosure | This is a compact single-purpose skill (~50 lines) with no bundle files (no references/, scripts/, or assets/ exist), and the body is organized into six well-labeled sections (When to survey, The survey, The report, Handoff, Non-goals, Completion definition) that are easy to navigate. The only file paths mentioned (CLAUDE.md, ADRs, docs/standards/architecture.md) are artifacts of the repo being surveyed, not skill-bundle references, so no nesting or splitting is needed. | 5 / 5 |
Total | 16 / 20 Passed |