Content
70%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 actionable, well-validated operations manual: every workflow carries concrete commands, exit-code semantics, and verification steps, with the learning loop as an exemplary feedback-rich protocol. Its weaknesses are structural, not instructional — the ~420-line monolith inlines envelope schemas, path contracts, and MCP setup that belong in one-level-deep reference files, and key caveats are repeated two or three times over.
Suggestions
Move the recall/teach envelope JSON schema, the path-and-state resolution contract, and the MCP HTTP server configuration into one-level-deep reference files (e.g. references/learning-loop.md, references/paths.md, references/mcp.md) with short pointers from SKILL.md.
Deduplicate the read-only restriction (stated in "When Not to Use This CLI", the Agent Mode "Read-only" bullet, and Direct Use) and the no-shell-interpolation caveat (repeated in Steps 1, 4, and 6) into a single stated-once rule.
Replace non-executable hedges like "use the category-specific Go fallback after publish" with the actual fallback command, or drop them until the publish state makes them actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with CLI-specific contract detail Claude cannot know (flags, envelopes, exit codes), but it is noticeably repetitive: the read-only restriction appears in "When Not to Use This CLI", the "Read-only" bullet, and again in Direct Use; the no-shell-interpolation caveat is repeated across Steps 1, 4, and 6; and "Purpose-built fixture for the OAuth2 device-code auth shape" is duplicated from the frontmatter. This fits 'mostly efficient but could be tightened' rather than anchor 4's 'minor instances'. | 3 / 5 |
Actionability | Most guidance is copy-paste executable — exact commands with flags (`printing-press-oauth2-pp-cli items --agent --select id,name`), full envelope JSON, exit-code table, MCP registration snippets — with minor gaps such as "use the category-specific Go fallback after publish" and "Run auth setup for setup details if needed", which are non-executable hand-waves. Not anchor 5 because these vague spots leave small holes in the common install/auth path. | 4 / 5 |
Workflow Clarity | The learning loop is a clearly sequenced six-step protocol with explicit validation checkpoints (verify `--version` before any command, `doctor`, confirm-payload-before-materialize on candidates, reject tombstoning) and genuine feedback loops (amend on divergence, confirm/reject on candidates); destructive operations are gated (`local-data purge` previews and requires `--yes`), so the destructive-cap does not apply. This matches the anchor-5 example's validate-fix-retry structure. | 5 / 5 |
Progressive Disclosure | There are no bundle files at all (no references/, scripts/, or assets/), so ~400 lines of material that clearly belongs in separate files — the recall/teach envelope schema, the path-resolution contract, MCP server configuration, the learning-loop protocol — are all inlined in SKILL.md. Section headers are good and navigation is possible (above anchor 2's 'no section headers' example), but content that should be split out is inline with no references, matching anchor 3. | 3 / 5 |
Total | 15 / 20 Passed |