Content
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is highly actionable and well-sequenced with strong validation checkpoints, and it wisely delegates heavy lifting to a bundled script. Its main weakness is conciseness — repeated warnings and inline detail (index schema, script internals, long gotchas) that could be tightened or moved to reference files.
Suggestions
De-duplicate the 'warn before building' / 'users hate hanging commands' guidance — state it once in Phase 1 and reference it from Phase 2 and Gotchas rather than repeating the full sentence three times.
Move the full index JSON schema and the 10-step 'What the script does, in order' enumeration into a reference file (e.g. references/INDEX_SCHEMA.md) and link to it, keeping SKILL.md a lean overview.
Trim the gotchas list by merging near-duplicates (e.g. the slug-keying and 'don't invent entities' points overlap with the Lookup rules and Phase 1 guidance) to reduce inline volume.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient and full of domain-specific guidance Claude wouldn't know, but padded with redundancy — 'Users hate commands that hang silently more than they hate one-line confirmations' and 'Always warn before building, even on the auto-trigger path' each recur across Phase 1, Phase 2, and Gotchas, and the 10-step 'What the script does, in order' re-explains logic already in the bundled script. | 2 / 3 |
Actionability | Fully executable main path — 'python3 "${CLAUDE_PLUGIN_ROOT}/skills/minutes-graph/scripts/graph_build.py" --incremental' — plus a concrete query-recipe table mapping each user question to a specific index lookup, a full index JSON schema, and a copy-paste ASCII chart format. | 3 / 3 |
Workflow Clarity | Clear Phase 0→1→2→3 sequence with explicit checkpoints: warn-before-build confirmation, mtime-based freshness check for incremental refresh, status JSON feedback (ok/fresh), and an upfront company/product detection guard that prevents the 'build → discover data isn't there → rebuild' loop. | 3 / 3 |
Progressive Disclosure | The heavy build logic is correctly externalized to scripts/graph_build.py (verified present and referenced), and sections are well-organized, but there are no reference files — the full index JSON schema, the 10-step script internals, and a 12-item gotchas list all live inline in SKILL.md, so content that could be split out remains in the overview. | 2 / 3 |
Total | 10 / 12 Passed |