How do I install the Searching Markdown skill?

Run npx skillmds@latest add diegosouzapw/searching-markdown in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Searching Markdown safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Searching Markdown?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Searching Markdown free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Searching Markdown?

diegosouzapw (@diegosouzapw) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Searching Markdown by diegosouzapw — Agent Skill

Name: Searching Markdown
Rating: 4.5 (4 reviews)
Author: diegosouzapw

Searching Markdown

Local semantic search for markdown documents using qmd. Combines BM25 full-text, vector semantic, and LLM re-ranking—all on-device. Use when searching notes, documentation, meeting transcripts, or knowledge bases. Triggers on: search markdown, find in notes, query documents, semantic search, search my docs.

diegosouzapw Updated Sep 8, 2026 54 repo stars

File contents

qmd: Local Markdown Search

On-device semantic search for markdown. Combines BM25 full-text search, vector embeddings, and LLM re-ranking locally via GGUF models.

Quick start

qmd search "keyword query"          # Fast BM25 full-text search
qmd vsearch "conceptual query"      # Vector semantic search
qmd query "complex question"        # Hybrid + LLM re-ranking (best quality)
qmd get notes/file.md               # Retrieve document (fuzzy matching)

Search commands

qmd search "<query>"                # BM25 full-text (fast, keyword matching)
qmd vsearch "<query>"               # Vector semantic (conceptual similarity)
qmd query "<query>"                 # Hybrid + re-ranking (best results, slower)

Search options

-n <num>              # Result count (default: 5; 20 with --files/--json)
-c, --collection      # Restrict to specific collection
--all                 # Return all matches (use with --min-score)
--min-score <num>     # Filter by relevance threshold (0.0-1.0)
--full                # Display complete document content
--line-numbers        # Add line annotations

Output formats

--files               # TSV: docid, score, filepath, context
--json                # Structured JSON with snippets
--csv                 # Comma-separated values
--md                  # Markdown output
--xml                 # XML serialization

Document retrieval

qmd get <filepath>                    # Get by path (fuzzy matching)
qmd get "#<docid>"                    # Get by 6-char document ID
qmd get <path>:<line> -l <count>      # Get from line, limit count
qmd multi-get "pattern/*.md"          # Multiple docs via glob
qmd multi-get "doc1.md, doc2.md"      # Comma-separated list
qmd multi-get "*.md" --max-bytes 20480  # Skip large files

Collection management

qmd collection add <path> --name <name>   # Create indexed collection
qmd collection add <path> --mask "*.md"   # Custom glob pattern
qmd collection list                       # List all collections
qmd collection remove <name>              # Delete collection
qmd collection rename <old> <new>         # Rename collection
qmd ls <collection>[/<subfolder>]         # List files in collection

Context & embeddings

qmd context add <path> "<description>"    # Add metadata to collection
qmd context list                          # View all contexts
qmd context rm <path>                     # Remove context
qmd embed                                 # Generate embeddings
qmd embed -f                              # Force re-embed everything

Maintenance

qmd status                            # Index health & collection info
qmd update                            # Re-index all collections
qmd update --pull                     # Pull remote repos before indexing
qmd cleanup                           # Remove cache & orphaned data

Score interpretation

Score	Relevance
0.8–1.0	Highly relevant
0.5–0.8	Moderately relevant
0.2–0.5	Somewhat relevant
0.0–0.2	Low relevance

Example: Setup and search workflow

# Index a collection
qmd collection add ~/notes --name notes
qmd context add qmd://notes "Personal notes and ideas"
qmd embed

# Search
qmd query "how does authentication work" -n 10 --min-score 0.3

# Get specific document
qmd get notes/auth-design.md

Example: Agent-friendly JSON output

qmd search --json "configuration" -n 10
qmd query --json "API design patterns" --min-score 0.5

---name: searching-markdowndescription: Local semantic search for markdown documents using qmd. Combines BM25 full-text, vector semantic, and LLM re-ranking—all on-device. Use when searching notes, documentation, meeting transcripts, or knowledge bases. Triggers on: search markdown, find in notes, query documents, semantic search, search my docs.---# qmd: Local Markdown SearchOn-device semantic search for markdown. Combines BM25 full-text search, vector embeddings, and LLM re-ranking locally via GGUF models.<installation>**First-time setup?** Read `references/installation.md` for install and configuration steps.</installation>## Quick start```bashqmd search "keyword query" # Fast BM25 full-text searchqmd vsearch "conceptual query" # Vector semantic searchqmd query "complex question" # Hybrid + LLM re-ranking (best quality)qmd get notes/file.md # Retrieve document (fuzzy matching)```## Search commands```bashqmd search "<query>" # BM25 full-text (fast, keyword matching)qmd vsearch "<query>" # Vector semantic (conceptual similarity)qmd query "<query>" # Hybrid + re-ranking (best results, slower)```### Search options```bash-n <num> # Result count (default: 5; 20 with --files/--json)-c, --collection # Restrict to specific collection--all # Return all matches (use with --min-score)--min-score <num> # Filter by relevance threshold (0.0-1.0)--full # Display complete document content--line-numbers # Add line annotations```### Output formats```bash--files # TSV: docid, score, filepath, context--json # Structured JSON with snippets--csv # Comma-separated values--md # Markdown output--xml # XML serialization```## Document retrieval```bashqmd get <filepath> # Get by path (fuzzy matching)qmd get "#<docid>" # Get by 6-char document IDqmd get <path>:<line> -l <count> # Get from line, limit countqmd multi-get "pattern/*.md" # Multiple docs via globqmd multi-get "doc1.md, doc2.md" # Comma-separated listqmd multi-get "*.md" --max-bytes 20480 # Skip large files```## Collection management```bashqmd collection add <path> --name <name> # Create indexed collectionqmd collection add <path> --mask "*.md" # Custom glob patternqmd collection list # List all collectionsqmd collection remove <name> # Delete collectionqmd collection rename <old> <new> # Rename collectionqmd ls <collection>[/<subfolder>] # List files in collection```## Context & embeddings```bashqmd context add <path> "<description>" # Add metadata to collectionqmd context list # View all contextsqmd context rm <path> # Remove contextqmd embed # Generate embeddingsqmd embed -f # Force re-embed everything```## Maintenance```bashqmd status # Index health & collection infoqmd update # Re-index all collectionsqmd update --pull # Pull remote repos before indexingqmd cleanup # Remove cache & orphaned data```## Score interpretation| Score | Relevance ||-------|-----------|| 0.8–1.0 | Highly relevant || 0.5–0.8 | Moderately relevant || 0.2–0.5 | Somewhat relevant || 0.0–0.2 | Low relevance |## Example: Setup and search workflow```bash# Index a collectionqmd collection add ~/notes --name notesqmd context add qmd://notes "Personal notes and ideas"qmd embed# Searchqmd query "how does authentication work" -n 10 --min-score 0.3# Get specific documentqmd get notes/auth-design.md```## Example: Agent-friendly JSON output```bashqmd search --json "configuration" -n 10qmd query --json "API design patterns" --min-score 0.5```

Frequently asked questions