Content
67%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 well-structured, largely actionable instruction skill with a concrete executable API call, clear step sequence, and good external reference hygiene. The main costs are token overhead from the redundant 'key insight' paragraph, the conformance-test-only Contract/Output Format boilerplate, and the time-sensitive endpoint-retirement note living inline instead of a deprecated section; a few integration patterns remain descriptive rather than executable.
Suggestions
Trim the 'The key insight' paragraph (it restates 'What this does') and the 'Contract'/'Output Format' sections that exist only 'for the conformance test' — move that contract text into the conformance test file itself; the Output Format section even cites section headers ('Output', 'Brain page format') that don't exist verbatim in the body.
Move the Sonar endpoint retirement details ('is being retired and refuses migrated accounts with 403 agent_api_migration_required') into a small 'Deprecated endpoints' subsection so the time-sensitive migration note doesn't bloat the primary invocation path.
Make the weaker integration patterns executable: show the actual put_page invocation for step 4 (currently just 'gbrain put research/<slug> # via the put_page operation') and give the cron deal/company monitoring pattern real commands or a preset flag instead of the single comment '# Weekly: pull recent news per company; flag changes for review'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient (tight tables, terse anti-patterns), but several sections could be trimmed: "The key insight: Perplexity doesn't just search — it reads and synthesizes" largely restates "What this does", and the trailing "Contract" / "Output Format" sections exist purely "for the conformance test" (~14 lines of meta boilerplate with no operational value). Time-sensitive API details ("the Sonar chat-completions endpoint ... is being retired and refuses migrated accounts with 403") sit inline in the invocation comments rather than a deprecated/old-patterns section. More than the 'minor instances' of the 4 anchor; far from the heavily padded 1-2 anchors. | 3 / 5 |
Actionability | Mostly executable: a copy-paste curl for POST /v1/agent with headers and JSON body, literal recency-filter JSON ("tools": [{"type": "web_search", "filters": ...}]), and concrete gbrain commands. Minor gaps: step 2's Perplexity query is a commented template ("Find: what's NEW since 2026-MM-DD ... Cite every claim."), step 4 is "gbrain put research/<slug> # via the put_page operation" without the actual put_page syntax, and the cron monitoring pattern is a bare comment ("# Weekly: pull recent news per company; flag changes for review"). Matches the 4 anchor; not 3 (the main path is genuinely runnable) and not 5 (several integration patterns are described rather than executed). | 4 / 5 |
Workflow Clarity | Clear numbered 1-5 sequence in Invocation (pull context → compose query → call API → put_page → cross-link) with per-failure recovery guidance in "When it fails" (retry after stated delay for rate_limited, answer from brain only when the key is rejected). Minor validation gaps keep it below 5: no checkpoint verifying the written page or citations before finishing, and the batch cron pattern's only safeguard is the comment "flag changes for review". Not 3 — the sequence is explicit and failure modes have concrete handling. | 4 / 5 |
Progressive Disclosure | No bundle files (references/, scripts/, assets/ absent); the body is one file with external references ([conventions/quality.md](../conventions/quality.md), [conventions/brain-first.md](../conventions/brain-first.md), agent-operator-protocol.md) that are one level deep and clearly signaled at the top, plus a Related skills section with explicit paths. Good sectioning throughout (What/When/Output/Invocation/Presets/Patterns/Fails/Anti-patterns). Minor gaps: the meta "Contract"/"Output Format" sections are trailing noise, and the Output Format section points at section names ("Output", "Brain page format") that don't literally exist. Matches the 4 anchor; not 5 because navigation could be cleaner and some inline material (full output template) argues for a lighter overview. | 4 / 5 |
Total | 15 / 20 Passed |