Content
50%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 exceptionally concrete, example-rich CLI reference that tells Claude exactly which commands to run, undermined by systematic duplication (Quick Reference and Important Caveats restate earlier content), command-name inconsistencies that would make some documented invocations fail, and a monolithic single-file structure with no progressive disclosure. Workflow guidance exists and is sequenced, but validation checkpoints are implicit and the end-to-end flows reference a nonexistent command.
Suggestions
Move the per-command reference (Synopsis/Arguments/Behavior details for lint, deploy, config, ls, etc.) into references/ files (e.g. references/commands.md, references/lint.md) and keep SKILL.md as an overview with the command tree, guidelines, and flows — the current 1,500-line monolith loads the entire reference into context on every invocation.
Delete the duplicated content: the Quick Reference section repeats the per-command synopses and the Important Caveats section restates Behavior bullets; keep one canonical location for each fact, and replace the six repeated "[path activation]" bullets with a single shared-pattern note.
Fix the internal inconsistencies before anything else: the end-to-end flows and Quick Reference use "generate module" where the actual command is "generate gear", "ls targets" and the "--dev/--build" flags of "ls deps" appear only in the Quick Reference with no documented section, and the "rest-api" template is used in an example but is not in the built-in template list — these would cause copy-paste failures.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | A 1,516-line body with systematic padding rather than incidental over-explanation: the "Quick Reference" repeats the per-command synopses already documented above, "Important Caveats" restates Behavior bullets nearly verbatim, the "[path activation]" bullet is repeated across six commands, and the "[exclusive boolean overrides]" explanation is duplicated between build and run — matching the score-2 anchor's several unnecessary padded sections rather than score-3's minor tightening opportunities. | 2 / 5 |
Actionability | Every command has a full synopsis, argument table, behavior bullets, and copy-paste-ready bash examples (e.g. "cargo gears config db add primary -p /tmp/cf-demo -c .../quickstart.yml --engine postgres --host localhost"), which meets the score-5 bar for executability, but command-name inconsistencies ("cargo gears generate module" in the flows and Quick Reference vs. the actual "generate gear" command, an undocumented "ls targets" and "--dev/--build" flags, a "rest-api" template example not in the template list) mean some documented commands would fail as written, dropping it to 4. | 4 / 5 |
Workflow Clarity | The "Practical End-to-End Flows" give a real sequence (generate workspace → generate config → config mod add → run) and the guidelines mandate verification ("Always verify that the application runs successfully after modifying the code"), but the flows contain a broken command name ("generate module"), steps have no explicit validation checkpoints between them (e.g. no "manifest validate" before build/deploy), and risky operations like deploy, clean, and tools have no verify/recovery loops — matching the score-3 anchor of sequence present but checkpoints missing or implicit. | 3 / 5 |
Progressive Disclosure | Internal structure is good (a command tree acts as a table of contents, and each command follows a consistent Synopsis/Arguments/Behavior/Examples pattern), but there are no bundle files at all: all ~1,500 lines — including the exhaustive lint flag semantics, help-topic catalog, and per-command argument tables — are inlined in SKILL.md, exactly the score-3 anchor's pattern of API-reference content that should live in separate files sitting inline; it avoids score 2 only because headers and the tree make it navigable. | 3 / 5 |
Total | 12 / 20 Passed |