Content
88%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 content is a highly actionable, well-validated operational guide: executable commands at every step, explicit failure and fallback behavior, and strong safety boundaries. Its main weakness is density — policy enumerations that belong in the referenced docs are inlined in SKILL.md, slightly bloating the overview.
Suggestions
Replace inline failure-mode enumerations (e.g., "A missing local Ollama service, malformed HTTP reply, missing selected model, unusable vector, or any candidate embedding failure falls back...") with the general rule plus one example, leaving the exhaustive list in docs/prefix-providers.md.
Compress the Contextual-prefix privacy section to the consent requirement plus a pointer, since the linked doc already holds "the exact policy, cloud model selection and verification limits".
Move the untagged-model/:latest alias-matching and 512-token truncation details into the referenced docs, keeping a single operational line in the Query section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and product-specific throughout — it explains nothing Claude already knows — but several passages enumerate every failure mode and policy nuance inline where a general rule plus the already-cited doc would do: "A missing local Ollama service, malformed HTTP reply, missing selected model, unusable vector, or any candidate embedding failure falls back...", the incremental-prefixing paragraph, and the untagged-model ":latest" alias rules. This fits anchor 4 (efficient with minor over-explanation that could be trimmed) better than 5, since not every token earns its place. | 4 / 5 |
Actionability | Every operational section gives copy-paste-ready bash: product-root resolution with `test -f` verification, provision commands (`--peek` preview, prefix, build, smoke-test retrieve), read-only query, diagnostics (`stats`, `query`, `--peek`), and the bench invocation. Only `$VAULT`/`$QUERY` placeholders remain, which is standard and expected; common cases are covered. | 5 / 5 |
Workflow Clarity | A clear sequence runs preview → prefix → build index → smoke-test retrieve → query, with explicit validation checkpoints (`test -f`, `--peek`, `--explain`, hash-match gates), an explicit error-recovery loop (exit 10 with a stable rebuild command; deterministic fallback to BM25 order), integrity rules, and a final checklist section. The destructive/batch cap of 3 does not apply: cache writes carry hash validation, fail closed under the vault-wide lock, and never touch canonical notes. | 5 / 5 |
Progressive Disclosure | Sections are clear and the two references ([prefix providers](../../docs/prefix-providers.md), [offline retrieval evaluation](../../docs/retrieval-evaluation.md)) are well-signaled and one level deep. However, the bundle contains only SKILL.md, and the body carries substantial policy detail inline (privacy/egress rules, model selection, tag aliasing, truncation limits) beyond a lean overview even though the linked doc is cited for "the exact policy" — a minor organization gap that fits anchor 4 rather than 5. | 4 / 5 |
Total | 18 / 20 Passed |