Content
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured, highly actionable skill with clear workflow sequencing and explicit validation checkpoints. Its main strength is the concrete, executable guidance at every step and the precise output template. Minor weaknesses include some unnecessary framing text in the introduction and a monolithic structure that could benefit from splitting detailed reference material into supporting files.
Suggestions
Trim the 'When to use' section to just the bullet list — the opening paragraph explaining what doc staleness is adds little value for Claude.
Consider extracting the report template and generated-artifact check details into a bundle reference file to improve progressive disclosure and reduce the main skill's length.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Generally efficient but includes some unnecessary framing (e.g., the 'When to use' section explaining what doc staleness is, and the metaphor about turning a table 'from a thing you're supposed to remember into a deterministic sweep'). The 'Do not' section is valuable but could be slightly tighter. Overall mostly lean but not maximally token-efficient. | 2 / 3 |
Actionability | Provides specific, executable commands throughout (git diff variants, pnpm openapi:check/generate, ln -s, ls -la). Each step has concrete actions with exact command syntax. The report template is copy-paste ready with precise formatting. The heuristics for staleness detection are specific and actionable. | 3 / 3 |
Workflow Clarity | Clear 5-step sequence with explicit validation checkpoints (run openapi:check before regenerating, verify symlinks exist, confirm ADR index consistency). Includes feedback loops (if openapi:check fails → regenerate → stage). Two distinct modes (patch vs report) are clearly delineated. The 'Do not' section provides important guardrails for destructive/scope-creep scenarios. | 3 / 3 |
Progressive Disclosure | The skill correctly delegates the doc-review mapping to AGENTS.md at runtime rather than inlining it (good design), and references external skills like write-adr. However, the content is moderately long (~100 lines) and could benefit from splitting the detailed generated-artifact checks or the report template into separate reference files. No bundle files are provided to support progressive disclosure. | 2 / 3 |
Total | 10 / 12 Passed |