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 'Use when' clause that addresses both what the skill does and when to use it. However, it lacks specificity in concrete actions beyond 'search' and could benefit from more distinctive trigger terms. The mention of 'QMD' adds some uniqueness but may not be a term users naturally use.
Suggestions
Add more specific concrete actions beyond 'search', such as 'query by keyword, filter by topic, retrieve relevant passages from markdown files'.
Expand trigger terms with natural variations users might say, such as 'knowledge base', 'wiki', 'lookup', '.md files', 'reference docs', or 'personal notes'.
| 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 'knowledge base', 'wiki', 'grep', 'query', or file extensions like '.md'. 'QMD' is a technical term that users may not naturally use. | 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, grep, 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 teaches Claude how to use QMD for markdown search. Its greatest strengths are conciseness and actionability — concrete JSON examples, CLI commands, and query syntax tables are immediately usable. Minor weaknesses include the lack of error handling/validation guidance and the content being somewhat long for a single SKILL.md without references to supplementary files.
Suggestions
Add a brief troubleshooting or validation section (e.g., how to verify a query returned relevant results, what to do when no results are found, or how to check collection health with `status`).
Consider splitting the detailed query syntax reference and HTTP API sections into separate referenced files to improve progressive disclosure.
| 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 setup section at the bottom lacks sequencing clarity (e.g., when to run `qmd embed`, what happens if embedding fails). The combining types table provides good decision guidance, but there are no validation checkpoints for verifying search results or troubleshooting poor results. | 2 / 3 |
Progressive Disclosure | The content is well-structured with clear sections and tables, but it's a fairly long single file that could benefit from splitting detailed query syntax and API reference into separate files. The MCP tools table hints at other capabilities without linking to further documentation. | 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.