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.
A lean, highly actionable body: exact commands, a numbered workflow with explicit validation and error-recovery routing, and a concrete output format. The only deductions are minor — the ask-first rule is restated in several sections, and the referenced convention files are not part of the bundle.
Suggestions
Consolidate the ask-before-fixing rule, which appears in Contract, findings step 5, Output Format, and Anti-Patterns, into one authoritative statement plus a single back-reference to save tokens.
Ensure the referenced convention files (`skills/conventions/brain-first.md`, `../conventions/agent-operator-protocol.md`) ship with or resolve from the skill's location, since no bundle files accompany SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient — exact commands (`gbrain advisor --json`, `gbrain advisor --apply <dispatch_id>`), exit-code semantics, and a compact JSON payload schema with no explanation of concepts Claude already knows. It is not a 5 because the ask-before-fixing rule is repeated in four places (Contract, findings step 5, Output Format, Anti-Patterns), which could be trimmed to one authoritative statement; it is well above a 3 since nearly every token earns its place. | 4 / 5 |
Actionability | Guidance is fully executable: the exact run command, the severity exit-code gate ("0 clean, 1 warn, 2 critical"), the JSON finding structure including `fix.command_argv`/`fix.dispatch_id` semantics, a copy-paste-ready cron job prompt with a concrete schedule, and a rendered output-format example. This matches the 'copy-paste ready commands; specific examples cover the common cases' anchor, including the unreachable-DB edge case. | 5 / 5 |
Workflow Clarity | The findings workflow is a clearly numbered 5-step sequence with explicit checkpoints: severity gate first, an ask-before-run decision point, a dispatch_id branch distinguishing auto-runnable vs manual fixes, and a dedicated "When it fails" section with error-recovery routing (e.g. the `GBRAIN_DB_ACCESS` marker routes to db-repair). Validation (exit-code gate) and feedback loops are explicit, matching the top anchor. | 5 / 5 |
Progressive Disclosure | The body is well-sectioned (Contract, When to run, How to run, findings workflow, cron recipe, output format, failures, anti-patterns) with nothing inlined that belongs in a separate file, and its two references (`skills/conventions/brain-first.md`, `../conventions/agent-operator-protocol.md`) are clearly signaled and one level deep. It is not a 5 because those referenced files do not exist within this bundle (no references/, scripts/, or assets/ directories), so the links cannot be resolved from what ships with the skill. | 4 / 5 |
Total | 18 / 20 Passed |