Content
77%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 exceptionally actionable, well-sequenced CLI-wrapping skill with strong validation loops for its destructive batch operations. Its weaknesses are moderate verbosity (duplicated trigger lists, motivational and historical narrative, generic YAML quoting rules) and a monolithic single-file layout that inlines detailed reference material a leaner SKILL.md would point to.
Suggestions
Delete the body 'Trigger words' section (it duplicates the frontmatter triggers field) and trim the 'Why This Exists' narrative and v0.37.5.0 quote-counter history to one line each.
Move the 'Prevention — Writing Valid Frontmatter' tutorial and the JSON output envelope into references/ files (e.g. references/writing-frontmatter.md, references/output-format.md), keeping SKILL.md an overview with clearly signaled links.
Drop the generic 'When to quote at all' YAML rules Claude already knows, keeping only the gbrain-specific canonical form (single-quoted flow style) and the LLM template-literal trap.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The bulk is dense, token-earning material (exact commands, flags, exit codes, hold-record fields), but roughly 30 of 267 lines could be cut: the 'Trigger words' section duplicates the frontmatter triggers field verbatim, 'Why This Exists' is a motivation narrative, the v0.37.5.0 quote-counter history is a war story, 'When to quote at all' teaches generic YAML quoting, and several cautions repeat across Output rules, When it fails, and Anti-Patterns. Fits anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened') better than 4's 'minor instances'. | 3 / 5 |
Actionability | Fully executable throughout: copy-paste-ready commands with complete flags ('gbrain repair frontmatter --source <id> --include-ambiguous --only <path> --apply --expect <hash> --yes'), exit-code semantics, backup paths, exact size limits (24 MiB / 5 MB), correct-vs-broken YAML examples, and a full JSON output envelope. Matches the 5 anchor: specific examples cover the common cases. | 5 / 5 |
Workflow Clarity | Phases 1-4 are clearly sequenced (audit, validate, fix, hook) with explicit validation checkpoints and feedback loops for a file-rewriting batch skill: '--dry-run' previews before batch fixes, '--diff' then hash-bound '--apply --expect <hash>', '--fix' 're-validates, and exits 1 when errors remain', mandatory user approval before every apply, and a 'When it fails' recovery section. The destructive/batch cap at 3 does not apply because validation is thorough — a clear anchor 5. | 5 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent), so all ~267 lines live in SKILL.md. Internal headers and one-level-deep external links ('docs/guides/repair.md#held-files', '../conventions/agent-operator-protocol.md') are clearly signaled, but substantial reference material is inlined where the rubric expects an overview — the ~55-line Prevention/YAML tutorial and ~35-line output-format spec belong in separate reference files. Fits anchor 3 ('content that should be separate is inline'); not 2, since structure and links are good, and not 4, given the volume of inlined detail. | 3 / 5 |
Total | 16 / 20 Passed |