memory-metadata-search

Structured metadata search for Basic Memory: query notes by custom frontmatter fields using equality, range, array, and nested filters. Use when finding notes by status, priority, confidence, or any custom YAML field rather than free-text content.

Quality

86%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A highly actionable, well-structured reference for the metadata-filter API with genuinely useful gotcha coverage. Its main weakness is redundancy: the quick-reference table, the usage section, and the Guidelines section each restate material already presented, inflating token cost without adding information.

Suggestions

Drop the per-operator subsections and keep only the Quick Reference table (or vice versa) — the operator syntax is currently shown twice, and the edge-case notes can be folded into whichever presentation remains.

Merge "The Tool" and "Using search_notes with Metadata" into a single section; both explain the same call pattern and the tags/status merging rules.

Trim the Guidelines section to only the decision guidance (metadata vs. text search, when to combine) and delete bullets that restate syntax rules from the Filter Syntax section.

Dimension	Reasoning	Score
Conciseness	The Quick Reference table restates every per-operator section above it, "Using search_notes with Metadata" repeats the intro from "The Tool", and "Guidelines" re-explains AND-logic, dot notation, and query-omission already covered earlier. It is efficient reference material with no concept-padding, but three redundant presentations push it below the 4 anchor ("minor instances that could be trimmed").	3 / 5
Actionability	All examples are executable Python against the real `search_notes` API, covering filter-only queries, text+metadata combinations, convenience shortcuts, tag shorthand, and a realistic worked example with sample frontmatter. Copy-paste ready guidance covering the common cases matches the top anchor.	5 / 5
Workflow Clarity	This is a single-action read-only skill (pass filters to `search_notes`) and the action is unambiguous, with explicit error-avoidance checkpoints: the `$`-prefix silent-failure warning, rejected null-in-operator semantics, and no-hit behavior for non-Markdown files. The simple-skill exception applies; no destructive/batch cap is relevant.	5 / 5
Progressive Disclosure	The body is well-sectioned with clear headers, a summary table, and a coherent flow from syntax to usage to worked example, and there are no bundle files so inline content is appropriate. It falls short of the 5 anchor because the full operator reference and extended example sections could plausibly be split into a separate reference file rather than kept entirely in SKILL.md.	4 / 5
	Total	17 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: third-person, concrete about capabilities, with an explicit 'Use when' clause carrying natural trigger terms. The only gap is that tag-based filtering — a major capability detailed in the body — is absent from the trigger list.

Dimension	Reasoning	Score
Specificity	"query notes by custom frontmatter fields using equality, range, array, and nested filters" enumerates multiple concrete actions covering all filter types the skill supports, matching the comprehensive anchor. It is not a 4 because the capability enumeration has no gaps.	5 / 5
Completeness	It explicitly answers what ("Structured metadata search for Basic Memory: query notes by custom frontmatter fields using equality, range, array, and nested filters") and when ("Use when finding notes by status, priority, confidence, or any custom YAML field rather than free-text content") with concrete trigger phrases, matching the top anchor exactly.	5 / 5
Trigger Term Quality	"status, priority, confidence, or any custom YAML field" gives good natural trigger coverage, but common user terms like "tags", "filter by", or "find notes" variations are missing from the description. Solid coverage with a few gaps fits the anchor for 4, not 5.	4 / 5
Distinctiveness Conflict Risk	It carves a clear niche (structured frontmatter queries within the named Basic Memory system) and explicitly contrasts itself with free-text search ("rather than free-text content"), minimizing conflict risk with a sibling text-search skill.	5 / 5
	Total	19 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: basicmachines-co/basic-memory
Path: skills/memory-metadata-search/SKILL.md
Commit: 194afe1

Reviewed: 7 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.