Mdq

LLM agent skills collection

Install

npx -y skills add akhy/agent-skills --skill mdq

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Query and filter Markdown documents using jq-like selector syntax — extract headings, list items, tasks, links, images, tables, code blocks, blockquotes, and paragraphs from markdown files. Useful for parsing README files, docs, changelogs, and any structured markdown.

SKILL.md

5.1 KB, ~1.3k tokens by cl100k_base, as published. Nobody here has run it

mdq Skill

mdq is a CLI tool for querying Markdown documents, analogous to how jq works with JSON.

Setup

Option 1: Homebrew (macOS/Linux)

brew install mdq

Option 2: Download Binary from GitHub Releases

Latest release: v0.9.0

# macOS (Apple Silicon)
curl -L https://github.com/yshavit/mdq/releases/download/v0.9.0/mdq-macos-arm64.tar.gz | tar xz
sudo mv mdq /usr/local/bin/

# Linux x86_64
curl -L https://github.com/yshavit/mdq/releases/download/v0.9.0/mdq-linux-x64.tar.gz | tar xz
sudo mv mdq /usr/local/bin/

# Linux x86_64 (musl/static)
curl -L https://github.com/yshavit/mdq/releases/download/v0.9.0/mdq-linux-x64-musl.tar.gz | tar xz
sudo mv mdq /usr/local/bin/

To get the latest release URL dynamically:

curl -s https://api.github.com/repos/yshavit/mdq/releases/latest \
  | jq -r '.assets[] | select(.name | test("macos-arm64")) | .browser_download_url'

Option 3: Docker

docker pull yshavit/mdq
docker run --rm -i yshavit/mdq '# heading' < file.md

Verify Installation

mdq --version

Usage

mdq [OPTIONS] <SELECTOR> [FILE]

If FILE is omitted, reads from stdin.

Options

Flag	Description
`-q`	Quiet mode — no output, exit 0 if matches found (grep-like)
`--output json`	Output results as JSON instead of Markdown

Selector Syntax

Selectors mirror Markdown syntax. All text matching is case-insensitive by default.

Headings

mdq '# title text' file.md        # any heading containing "title text"
mdq '## ' file.md                  # all h2 headings
mdq '# *' file.md                  # all headings (any level)

Lists

mdq '- item text' file.md          # unordered list items
mdq '1. item text' file.md         # ordered list items

Tasks

mdq '- [ ] task' file.md           # uncompleted tasks
mdq '- [x] task' file.md           # completed tasks
mdq '- [?] task' file.md           # any task (complete or not)

Links and Images

mdq '[display](url)' file.md       # links (match on display text or url)
mdq '![alt](url)' file.md          # images
mdq '[](https://example.com)' file.md  # links by URL

Block Quotes

mdq '> quote text' file.md

Code Blocks

mdq '```language code' file.md     # fenced code blocks
mdq '``` ' file.md                  # all code blocks

HTML Elements

mdq '</> div' file.md              # HTML elements by tag name

Paragraphs

mdq 'P: text' file.md

Tables

mdq ':-: header :-: row' file.md  # match by header and row content
mdq ':-: Status' file.md           # tables with a "Status" header

Front Matter

mdq '+++yaml text' file.md         # YAML front matter
mdq '+++toml text' file.md         # TOML front matter

Text Matching

Pattern	Behavior
`word`	Unquoted — case-insensitive substring match
`"Word"` / `'Word'`	Quoted — case-sensitive substring match
`^prefix`	Anchored to start
`suffix$`	Anchored to end
`/regex/`	Regular expression match
`!s/regex/replace/`	Regex replace in output
`*` or omitted	Wildcard — matches anything

Chaining Selectors (Pipe)

Use | to chain filters sequentially (output of each feeds the next):

mdq '# Installation | - ' file.md    # list items under "Installation" heading
mdq '## * | - [x]' file.md           # completed tasks under any h2

Examples

# Extract all h2 headings from a README
mdq '## ' README.md

# Find all uncompleted tasks
mdq '- [ ]' TODO.md

# Get all links as JSON
mdq --output json '[]()' README.md

# Check if all tasks are complete (exit code 0 = none found = all done)
mdq -q '- [ ]' checklist.md && echo "All done!" || echo "Tasks remaining"

# Extract links under a specific section
mdq '# Resources | []()' README.md

# Find code blocks in bash
mdq '```bash' README.md

# Get table rows matching a value
mdq ':-: Status :-: done' report.md

# Pipe from stdin
cat file.md | mdq '# *'

JSON Output

Use --output json to get structured output for programmatic use:

mdq --output json '- [ ]' file.md | jq '.[].text'
mdq --output json '[]()' README.md | jq '.[] | {text: .link_text, url: .url}'