Content
75%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.
Highly actionable content: executable CLI commands, a defined JSON output contract, a complete macro schema, and a dry-run-first workflow. The main cost is token redundancy — the duplicated Quick Start/Example Workflow sections and the restated concept section could be cut — and the ~40-line schema could move to a reference file.
Suggestions
Merge 'Quick Start' and 'Example Workflow' into one section — they demonstrate the identical list → info → dry-run → run sequence and cost ~18 redundant lines.
Drop or shrink 'What It Is'; it repeats the frontmatter description, and the one non-duplicated fact ('agents never touch the GUI directly') can open the Quick Start.
Move the full macro YAML schema (~40 lines) to a references/ file (e.g. references/macro-schema.md), keeping only the scaffold command and a pointer in SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly lean command tables and code, but 'Quick Start' and 'Example Workflow' are near-duplicate demonstrations of the same list → info → dry-run → run sequence (~18 redundant lines), and 'What It Is' restates the frontmatter description. This is more than 'minor instances of over-explanation', so it sits at 'mostly efficient but could be tightened'. | 3 / 5 |
Actionability | Every section gives copy-paste-ready commands ('cli-anything-macrocli macro run export_file --param output=/tmp/result.txt --json'), a fully specified JSON output shape, and a complete minimal macro YAML schema with params, preconditions, postconditions, and agent_hints — fully executable guidance covering the common cases. | 5 / 5 |
Workflow Clarity | The Example Workflow sequences discovery → inspect → dry-run validation → execution ('Step 3: Test safely', 'Step 4: Execute for real'), and failure handling is addressed ('Read error field when success is false'). It falls short of a 5 because there is no explicit fix-and-retry feedback loop after a failed run. | 4 / 5 |
Progressive Disclosure | A single-file skill (no bundle files exist) with clear, navigable sections (Command Reference, Parameters, Output Format, Backends, Writing Macros, Usage Rules) and nothing buried or nested. Not a 5: at ~210 lines, the full macro YAML schema and complete command tables are inlined where a references/ file could carry them; not a 3 since the structure is well-organized and easy to navigate. | 4 / 5 |
Total | 16 / 20 Passed |