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.
The body is an exemplary CLI-workflow skill: copy-paste-ready commands with exact payloads, an explicitly sequenced state-machine loop with validation gates, error-recovery branches for interrupted workflows and broken footprints, and confirmation checkpoints before destructive edits. Its only real weaknesses are the triple-repeated "do not stop after one command" warning and an undifferentiated single file where some reference material could be split out.
Suggestions
Consolidate the repeated "don't stop after one command" guidance (STOP blockquote, loop paragraph, and 'Concretely' paragraph) into a single authoritative statement to trim tokens.
Consider moving the Materialization/staleness and Concepts detail into a references/ file, keeping SKILL.md as a tighter overview with clearly signaled one-level-deep references.
The version-check preamble and trace-span instructions appear before any context about the skill; a brief orientation line before them would aid navigation.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Commands are exact and Concepts teaches genuinely novel domain facts (footprint vs. source, colocated/separate repos) Claude cannot already know, but the "don't stop after one command" message is repeated three times (the STOP blockquote, "This is a loop. Do not stop after the first step.", and "Concretely: do not stop after `repo new`."). Not 5 because that repetition is trimmable; not 3 because there is no padding explaining things Claude already knows. | 4 / 5 |
Actionability | Every command is copy-paste ready with exact JSON payloads (`spektacular repo new --data '{"location":"<folder>"}'`, `repo goto --data '{"step":"<current_step>"}'`, the direct `repo add --data '{...}'` form), and the common cases are all covered: guided add, pre-supplied location, interrupted-add resume, fresh start with `--force`, scripting form, footprint repair, and manual removal. Fully executable guidance with no gaps. | 5 / 5 |
Workflow Clarity | The add workflow is a clearly sequenced loop (instruction → step → goto) with explicit validation gates up front (`spektacular version check`, gating on `status: "match"`), feedback loops for error recovery (resume-report `kind` check, `repo_footprint_missing` → repair paths, `--status error` on failed trace spans), and user-confirmation checkpoints before destructive edits ("Confirm with the user before editing their config"). Not 4 because checkpoints and recovery paths are explicit, not merely present. | 5 / 5 |
Progressive Disclosure | The single-file body is well-sectioned (When to invoke / Concepts / Adding / Inspecting / Materialization / Repair / Removal) with no nested or broken references — no bundle files exist to reference. At ~140 lines covering the whole repo surface, content like Materialization and staleness or the Concepts section could arguably live in a separate reference file, a minor organization gap. Not 5 because content is not split at all and the 50-line simple-skill exception doesn't apply; not 3 because structure and navigation are genuinely good. | 4 / 5 |
Total | 18 / 20 Passed |