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.
Highly actionable and unambiguous: complete filter syntax, executable examples, edge-case rules, and clear tool selection guidance. The main cost is redundancy — the Quick Reference table, the bm_search example section, and the worked "Custom Frontmatter in Practice" section repeat substantially the same operators and queries, which inflates token cost without adding guidance.
Suggestions
Collapse the duplication: the Quick Reference table already covers every operator, so trim the "Example: Custom Frontmatter in Practice" queries and the Guidelines bullets that restate filter rules (AND logic, omitting query, dot notation) to single mentions.
Move the worked note example plus the full operator table into a reference file (e.g. references/filter-reference.md) and keep SKILL.md to the syntax summary and a few canonical bm_search examples, bringing the body closer to overview length.
Trim the tangents that serve other skills' workflows — the observation-qualifier/valid_at paragraph already defers to memory-notes, so a one-line pointer would do, and the 400-digit-integer rule can be shortened to "bounds must be finite numbers".
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The same examples appear repeatedly — `{"confidence": {"$gt": 0.7}}` is shown in Comparisons, the Quick Reference table, the bm_search section, and the Custom Frontmatter example, and the Guidelines section restates rules already given ("Multiple filters are AND", "Omit `query` for filter-only searches", "Dot notation for nesting"). This is more than the minor over-explanation of anchor 4 but well short of the concept-explaining padding of anchor 2, so it sits at anchor 3: mostly efficient but could be tightened. | 3 / 5 |
Actionability | Fully executable copy-paste Python throughout (`bm_search(filters={"status": "in-progress"}, project="<project>")`), a complete JSON filter syntax with every operator, a quick-reference table, and explicit edge-case rules (non-empty lists, `$between` bounds, null semantics, key regex). The `<project>` placeholder is explained up front, so examples run as-is once substituted. | 5 / 5 |
Workflow Clarity | A simple single-purpose skill where the action is unambiguous ("Use `bm_search` for ranked results or `bm_find` for file discovery... Omit `query`... for filter-only searches"), which qualifies for the simple-skill exception. The project-scoping mini-workflow is sequenced with edge handling — discover via `bm_project(command="list")`, keep scope when "following returned paths, paginating, or recovering from a refusal" — and nothing here is destructive or batch, so no validation cap applies. | 5 / 5 |
Progressive Disclosure | No bundle files exist, and the body is well organized with clear sections (When to Use, The Tool, Filter Syntax, Quick Reference, Guidelines) plus a one-level pointer to the memory-notes skill for observation qualifiers. It misses anchor 5 because at ~220 lines (over the 50-line simple-skill threshold) the full operator reference and the worked example section are inlined where a reference file could carry the bulk; structure is good but the split is not optimal. | 4 / 5 |
Total | 17 / 20 Passed |