qmd
Search markdown knowledge bases, notes, and documentation using QMD. Use when users ask to search notes, find documents, or look up information.
81
73%
Does it follow best practices?
Impact
97%
1.49xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/qmd/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description is structurally sound with a clear 'what' and 'when' clause, earning full marks on completeness. However, it lacks specificity in concrete actions beyond 'search' and uses the technical term 'QMD' without explanation, while its trigger terms are somewhat generic and could overlap with other search-oriented skills.
Suggestions
Add more specific concrete actions beyond 'search', such as 'filter by tags, search by title or content, retrieve specific entries from markdown knowledge bases'.
Expand trigger terms with natural variations users might say, such as 'query notes', 'find in knowledge base', 'lookup documentation', '.md files', or 'search wiki'.
Clarify what QMD is or remove the acronym if it doesn't help with skill selection, and add distinguishing details about what makes this different from general file search.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (markdown knowledge bases, notes, documentation) and one action (search using QMD), but doesn't list multiple concrete actions beyond searching. It's more specific than 'helps with documents' but doesn't enumerate distinct capabilities. | 2 / 3 |
Completeness | Clearly answers both 'what' (search markdown knowledge bases, notes, and documentation using QMD) and 'when' (when users ask to search notes, find documents, or look up information) with an explicit 'Use when' clause. | 3 / 3 |
Trigger Term Quality | Includes some natural keywords like 'search notes', 'find documents', 'look up information', but misses common variations users might say such as 'query', 'knowledge base', 'lookup', 'grep', 'find in notes', or file extensions like '.md'. The term 'QMD' is technical jargon that users are unlikely to use naturally. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'QMD' and 'markdown knowledge bases' provides some distinctiveness, but 'search notes' and 'find documents' are fairly generic triggers that could overlap with file search tools, grep-like skills, or general document retrieval skills. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
79%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, actionable skill that efficiently documents the QMD tool with concrete examples, executable code, and well-organized reference tables. Its main weaknesses are the lack of error-handling/feedback guidance when searches return poor results, and the amount of reference material that could be offloaded to separate files for better progressive disclosure.
Suggestions
Add a brief troubleshooting/feedback loop section (e.g., 'If results are poor: broaden with vec/hyde, check collection filtering, verify index is up to date with `qmd status`').
Consider moving the detailed Lex Query Syntax table, HTTP API section, and CLI reference to a separate REFERENCE.md file, linking from the main skill.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient throughout. It uses tables for compact reference, avoids explaining what markdown or search engines are, and every section delivers actionable information without filler. No unnecessary preamble or concept explanations. | 3 / 3 |
Actionability | Provides fully executable JSON payloads for MCP queries, concrete CLI commands, curl examples for the HTTP API, and specific setup commands. The query writing guidance includes concrete examples with exact syntax rather than abstract descriptions. | 3 / 3 |
Workflow Clarity | The skill is primarily a reference/tool guide rather than a multi-step workflow, but the 'Combining Types' table and query guidance provide clear decision logic. However, there's no explicit validation or feedback loop for when queries return poor results (e.g., 'if no results, try expanding with hyde'). | 2 / 3 |
Progressive Disclosure | The content is well-structured with clear sections and tables, but it's somewhat long for a single SKILL.md file. The detailed query syntax reference, HTTP API, and CLI sections could be split into separate reference files. However, sections are clearly labeled and navigable. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
Total | 10 / 11 Passed | |
- Reviewed
Table of Contents
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.