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.
The body is highly actionable — complete command syntax, failure semantics, examples, and output format — with an unambiguous workflow and an explicit empty-result recovery loop. Its weaknesses are redundancy (a duplicated Mindset section, Never bullets restating the Anti-Patterns) and an unclear split between SKILL.md and references/query-tips.md, which overlap heavily instead of layering.
Suggestions
Merge the two '## Mindset' sections into one — the opening section and the near-identical one after '## Never' both tell the agent to search before re-deriving, so keep a single instance near the top.
Fold the '## Never' bullets into '## Anti-Patterns' — three of the four 'Never' items restate an anti-pattern entry verbatim in spirit (search-first, never fabricate, noun-phrase queries), so one consolidated section removes ~10 lines.
Deduplicate references/query-tips.md against the body: either move the query-construction detail wholly into the reference and keep a one-line pointer in SKILL.md, or drop the reference — currently it repeats Mindset, Query construction, and Handling-no-results content rather than adding a second layer.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Individual sections are tight and free of concept over-explanation, but there is real redundancy: a "## Mindset" section appears twice ("Search before you implement, design, or debug" at the top and "Search memory first; do not re-derive what was already decided" near the end), and the "## Never" bullets largely restate the "## Anti-Patterns" entries (e.g. "Never skip search before a non-trivial implementation task" vs. "NEVER re-implement something without searching memory first"). This fits anchor 3 — mostly efficient but could be tightened — rather than anchor 4, because an entire section is duplicated, and not anchor 2, since no space is spent explaining things Claude already knows. | 3 / 5 |
Actionability | Provides the complete command signature `vault-cli search "<query>" [--top-k <n>] [--project <id>]`, its failure behavior ("Exits 1 with 'No results.'"), four copy-paste-ready example invocations, concrete good/bad query-construction contrasts ("auth token expiry" not "how does auth token expiry work?"), and the exact output format. Fully executable guidance covering the common cases — anchor 5; anchor 4 would require minor gaps in the commands or examples, and none are evident. | 5 / 5 |
Workflow Clarity | The single action is unambiguous, and the failure path is an explicit numbered sequence with a feedback loop: "1. Retry with a broader synonym query / 2. If still empty, tell the user… / 3. Never invent…", reinforced by the broaden-and-retry guidance in Query construction. It is a simple non-destructive skill, so the missing-validation cap does not apply, and the explicit retry loop places it at anchor 5 rather than anchor 4 (checkpoints are present, not mostly present). | 5 / 5 |
Progressive Disclosure | Sections are clearly headed, and the single reference — "[Vault Search: Query Tips](references/query-tips.md)" — is a real, one-level-deep, well-signaled file. However, the body runs ~88 lines (past the under-50-line simple-skill exception), and references/query-tips.md substantially duplicates body content ("Search before implementing…" ≈ Mindset/When to use; "Use concrete nouns from the task, not the literal user phrasing" ≈ Query construction; "Treat a miss as signal" ≈ Handling no results), so the split between overview and reference is not clean. This is anchor 4 (good structure, references mostly clear, minor organization gaps) rather than anchor 5, and above anchor 3 because the reference is explicit and not buried. | 4 / 5 |
Total | 17 / 20 Passed |