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.
An exemplary CLI-operation skill: fully executable commands, deterministic decision rules, and explicit validation and safety checkpoints for every destructive or batch path. The two improvement levers are token efficiency (safety guidance is stated redundantly across sections) and progressive disclosure (a 350-line monolith that could move reference material into a references/ file).
Suggestions
Split reference-like material (full tag and preset command listings, legacy sync details, adopt --git-url edge cases) into a references file linked from the relevant sections, keeping SKILL.md as the operational overview.
Consolidate the repeated destructive-operation guidance (never delete conflicts, never pass --force, never remove-then-reinstall) into one 'Safety rules' callout instead of restating it in the deploy, update, set-source, and pitfalls sections.
Trim the bridge-resolution prose in 'Before doing anything' to the three outcomes and their one-line verdicts; the rationale paragraphs restate what the outcomes already say.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Almost every passage carries CLI-specific facts Claude cannot know (the .version stamp logic, held_back_removals semantics, --subpath vs --git-subpath, adopt's late failure), with no explanation of known concepts. It falls short of lean-perfect because safety warnings are repeated across sections (e.g., destructive-force guidance restated, and Pitfalls re-explains material already covered). | 4 / 5 |
Actionability | Every operation ships a copy-paste command with exact flags, a deterministic ref-resolution rule, and real machine-readable error payloads (TARGET_CONFLICT JSON, held_back_removals), fully covering the common cases — squarely the copy-paste-ready anchor. | 5 / 5 |
Workflow Clarity | Typical workflows map user requests to numbered sequences with explicit validation ('Always verify after install' via skills list/show, skills status to confirm deployment), --dry-run previews precede every batch/destructive operation, check precedes update, and the Pitfalls section provides error-to-fix recovery loops, so the destructive/batch cap at 3 does not apply. | 5 / 5 |
Progressive Disclosure | A ~350-line single-file skill with well-organized sections (mental model, per-command sections, workflows, pitfalls) and no wall-of-text problem, but no bundle references at all — reference-like material (full tag/preset command listings, adopt edge cases, legacy sync) could be split into one-level-deep reference files, keeping it below the well-signaled-references anchor. | 4 / 5 |
Total | 18 / 20 Passed |