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.
The body is an unusually strong operational manual: fully executable commands, a correctly sequenced import/backfill pipeline with real validation checkpoints and error-recovery feedback loops, and dense project-specific knowledge with essentially zero generic filler. Its two weaknesses are structural: the same critical rules are restated three or four times across the Invariants, Anti-Patterns, and Contract sections (conciseness), and everything lives inline in one long file with no reference bundle for the detailed catalogs (progressive disclosure).
Suggestions
De-duplicate the triple restatement: keep the three invariants in their root-caused section and have the Anti-Patterns and Contract sections reference them by name ('invariant 2') instead of re-explaining each one.
Move the detailed catalogs — the redaction/PII pattern list, the native-vs-manual delta, and the append_page concurrency mechanics — into a references/ file (e.g. references/redaction-patterns.md, references/append-semantics.md) and keep one-line pointers in SKILL.md, shortening the body substantially.
The Contract section's admission that it 'exists for the conformance test' duplicates the body wholesale; consider generating or condensing it to a short bulleted guarantee list that cites the governing sections.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is genuinely dense — nearly every line is project-specific operational knowledge (gbrain CLI semantics, page ceilings, CAS/slug-collision behavior, --max-bytes checkpoint fingerprinting) with no explanations of concepts Claude already knows. However, the same rules are restated multiple times: the three invariants appear in their own section, again in Anti-Patterns, and again in the Contract; secret/PII redaction rules appear in Step 1.5, the native-vs-manual delta paragraph, Anti-Patterns, and the Contract; slug-collision guidance appears three times. That deliberate triple-statement plus a Contract section that admits it 'exists for the conformance test' is more than minor over-explanation — it fits 'mostly efficient but could be tightened'. | 3 / 5 |
Actionability | Guidance is copy-paste ready throughout: exact CLI invocations with flags ("gbrain transcripts ingest ~/Downloads/conversations.json", "gbrain extract-conversation-facts --types conversation --dry-run --limit 5", "gbrain conversation-parser scan conversations/chatgpt/2025-03-15-agent-memory", "gbrain append <slug> --file new.md"), a complete page template with required frontmatter, named parser patterns with exact line shapes, and concrete output-format templates for the import receipt and tracing answer. The one absent artifact — a full converter script — is explicitly justified ('Provider formats drift between export versions — inspect the actual JSON before writing the converter'), satisfying the pseudocode exception. | 5 / 5 |
Workflow Clarity | The import procedure is a clearly sequenced six-step pipeline (parse → redact pre-write → convert → trial-before-bulk → import → parser validation → fact extraction) with explicit validation checkpoints at exactly the right places: 3-5-conversation trial run before bulk, gbrain conversation-parser scan before bulk conversion, --dry-run cost preview before the paid run, and a gap diff where 'a second pass reporting zero gaps is the done signal — one pass is not'. Feedback loops are spelled out for error recovery (fix the converter and regenerate rather than hand-patch; resume_command after a cost-cap stop; tail_changed refusal → re-read → append again), meeting the top anchor for a batch workflow. | 5 / 5 |
Progressive Disclosure | Section headers are clear and every cross-link to sibling skills/conventions is clearly signaled with its purpose (one level deep, never nested), so navigation is not the problem. But this is a ~450-line monolithic SKILL.md with no bundle files at all (no references/, scripts/, or assets/ exist) — detailed catalogs that would fit reference files (the redaction pattern catalog, the three-invariants root-cause narrative, the append/edit_page concurrency mechanics, the native-vs-manual delta) are all inlined, matching 'content that should be separate is inline' with good-but-not-optimal organization. | 3 / 5 |
Total | 16 / 20 Passed |