Content
81%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 strong, dense operational skill body: concrete commands, explicit preview/apply validation for destructive actions, and thorough error-recovery guidance with clearly signaled external references. The main weaknesses are repeated rules across sections and dependence on remote documentation URLs rather than bundled reference files for exact command syntax.
Suggestions
State the unknown-outcome transport rule, the list-failure rule, and the broader-scopes prohibition once (in "When it fails") and reference them from the action sections, trimming the duplicated sentences.
Bundle ADMIN.md (or a command-reference extract) locally alongside the skill so exact command syntax is available without the remote GitHub/raw URL dependency.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes Claude's competence — no explanation of OAuth, PKCE, or MCP fundamentals — with nearly every sentence carrying GBrain-specific operational rules. It falls short of anchor 5 because several rules are stated twice (the unknown-outcome transport rule, "a failed list is not an empty list", and "do not try successively broader OAuth scopes" each appear in both the action sections and "When it fails"). | 4 / 5 |
Actionability | Concrete subcommands and flags throughout — `login-link --oauth-request ID`, `mcp grant NAME --client ID --if-version N --dry-run`, `--yes --if-version N`, `--credentials-out PRIVATE_FILE` — make the guidance mostly executable. The `gbrain mcp admin … --url URL` placeholder and deferral of full syntax to the external ADMIN.md leave minor gaps that keep it from anchor 5's copy-paste-ready standard. | 4 / 5 |
Workflow Clarity | Destructive operations carry explicit validation checkpoints: dry-run previews before/after, `--if-version` concurrency guards, apply only after review, `whoami` confirmation afterwards, and verification via an authenticated call from the native harness. Error-recovery feedback loops are thorough — unknown-outcome handling, grant_diagnosis relay, and hidden_tool_content fix paths — matching anchor 5. | 5 / 5 |
Progressive Disclosure | Sections are clearly organized and references are one level deep with stated purpose (ADMIN.md "for the exact commands and recovery table", the hosted guide for installation, DEPLOY.md for the running service, plus a raw-URL fallback). It misses anchor 5 because all references are remote URLs rather than bundled files, and substantial operational detail is inlined in SKILL.md instead of being split out. | 4 / 5 |
Total | 17 / 20 Passed |