Content
82%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 highly operational skill body: real CLI commands with flags, a concrete context-expansion ladder, a disciplined evidence-to-action synthesis template, and hard rules against fabrication and book-report fluff. The main improvement opportunities are removing the duplicated trigger-cue and expansion-pace text, and adding an explicit recovery path for poor or empty retrieval results.
Suggestions
Drop the 'When to Use' trigger-cue list (it duplicates the frontmatter description) and keep the single 'Start narrow, expand only when needed' statement in one place to tighten conciseness.
Add a brief fallback step to the retrieval workflow for empty or weak search results (e.g. re-query with broader terms, try --concept facets, or fall back to docs summary/toc) to close the workflow feedback-loop gap.
Consider moving the API-path endpoints and the full taxonomy listing into a small reference file to keep SKILL.md as a lean overview.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious, system-specific detail (chunking design, embedding config, artifact paths, CLI flags) and assumes competence throughout. Minor trimming exists: the 'When to Use' section repeats trigger cues already in the frontmatter description, and 'Start narrow, expand only when needed' / 'Don't dump full books into context' appears in both the expansion-strategy section and the Rules section. Efficient with minor over-explanation fits anchor 4 rather than 5. | 4 / 5 |
Actionability | Commands are copy-paste ready with real flags and values ('joelclaw docs search "distributed consensus" --limit 8', 'joelclaw docs context <chunk-id> --mode snippet-window --before 2 --after 2', 'joelclaw docs markdown <doc-id>') plus concrete API endpoints, taxonomy filters, and a structured ledger/action template. Fully executable guidance covering the common cases matches anchor 5. | 5 / 5 |
Workflow Clarity | Clear progressive retrieval sequence (numbered 1-5 expansion ladder with 'Start narrow, expand only when needed') and a well-structured synthesis workflow whose output template embeds validation gates, failure signals, and rollback moves. Not 5 because there is no explicit feedback loop for error recovery, e.g. what to do when search returns nothing useful or a chunk-id fails to expand. This is analysis-only, not destructive or batch, so no cap applies. | 4 / 5 |
Progressive Disclosure | No bundle files exist; the single ~135-line SKILL.md is well organized with clear section headers. It exceeds the under-50-line simple-skill exception and inlines an API reference and full taxonomy listing that could arguably live in separate reference files, so 'good structure; most content appropriately placed; minor organization gaps' (anchor 4) is the best fit rather than 5. | 4 / 5 |
Total | 17 / 20 Passed |