mdq

name	mdq
description	This skill should be used when the user asks to parse, search, grep, query, filter, or extract headings, sections, tasks, code blocks, links, or tables from Markdown files. Use when working with mdq, jq-style Markdown querying, section extraction, checklist validation, CI task scripts, or documentation automation pipelines.
version	2.0.1

Provide usage patterns for mdq, a CLI tool that queries Markdown documents using selector syntax mirroring Markdown itself. mdq applies jq-style querying to Markdown files. Selectors mirror Markdown syntax, making queries intuitive. Results output as Markdown (default), JSON, or plain text.

Basic usage: mdq [OPTIONS] [SELECTORS] [FILE...] Reads stdin if no file is given. Multiple files are concatenated.

# title Select a section by heading. Matches the heading and all content until the next same-level heading. mdq '# installation' README.md mdq '# /getting.started/i' README.md - item Select unordered list items matching text. mdq '- getting started' README.md mdq '-' README.md 1. item Select ordered list items matching text. mdq '1.' steps.md - [ ] text (unchecked) / - [x] text (checked) / - [?] text (any) Select task list items by completion state. mdq '- [ ]' tasks.md mdq '- [x]' tasks.md mdq '- [?]' tasks.md ```language text Select fenced code blocks, optionally filtering by language or content. mdq '```rust' guide.md mdq '```' README.md [display](url) Select links by display text and/or URL pattern. Use * or empty to match any. mdq '[](github.com/)' docs.md mdq '[install](*)' README.md  Select images by alt text and/or URL. mdq '' README.md :-: column :-: row Select table rows. First :-: matches column header, second matches row content. mdq ':-: /Name/ :-: *' schedule.md mdq ':-: * :-: Alice' schedule.md > text Select block quotes matching text. mdq '> note' docs.md P: text Select paragraphs matching text. mdq 'P: /deprecated/' CHANGELOG.md

<string_matching> Case-insensitive, must start with a letter. Example: installation Case-sensitive with escape sequences. Example: "Getting Started" /pattern/ using fancy-regex. Example: /getting.started/i * or empty matches anything. ^start or end$ for position anchoring. </string_matching>

Chain selectors with | to filter within results. # Extract unordered lists from the "Usage" section mdq '# usage | -' README.md

# Get code blocks from the "Examples" section
mdq '# examples | ```' guide.md

# Find checked tasks in the "Release" section
mdq '# release | - [x]' CHANGELOG.md

<output_options>

Default. Outputs valid Markdown. JSON array for piping to jq or other tools. Plain text without Markdown formatting. Suppress stdout; exit code 0 if match found, 1 if not. Inline links instead of reference-style. Keep links in their original format (default is reference). Check if all tasks are completed (exit code 0 = all done) # Fail if any unchecked tasks remain mdq -q '- [ ]' pull_request_template.md && echo "All done" || echo "Incomplete tasks" Extract all links as JSON for further processing mdq '[](*)' --output json docs.md | jq '.[].url' Extract a specific section to a new file mdq '# api reference' README.md > api.md Extract code examples by language mdq '```python' tutorial.md --output plain Combine mdq and jq for complex document processing mdq '# changelog | - [x]' CHANGELOG.md --output json | jq 'length'

<decision_tree name="when_to_use_mdq"> Do you need to extract or query specific elements from a Markdown file? Use # selector, optionally chain with child selectors Use - [ ] / - [x] / - [?] selectors; use -q for scripting Use selector with --output json for structured data Use ``` selector with optional language filter Use standard text tools (grep, awk) or a Markdown parser library </decision_tree>

<best_practices> Chain selectors with | to narrow scope before extracting child elements Use --quiet (-q) and exit codes in CI/CD scripts instead of parsing stdout output Use --output json when piping results to jq or other structured-data tools Use regex selectors /pattern/i for case-insensitive matching in cross-platform environments Prefer --output plain for text processing pipelines that do not need Markdown formatting </best_practices>

<anti_patterns> Applying mdq to non-CommonMark formats (AsciiDoc, RST, HTML) expecting Markdown-like results Use mdq only on CommonMark Markdown files; use format-specific tools for other document types

Parsing mdq stdout in CI/CD to detect presence or absence of matches Use --quiet (-q) flag and check exit code: 0 means match found, 1 means no match Selecting deeply nested elements without first narrowing scope with a parent selector Chain selectors (e.g., '# section | - [x]') to restrict extraction to the intended context Always chain selectors with | when extracting child elements to prevent scope bleed across sections Never parse mdq stdout in CI/CD; always use --quiet and check exit code (0 = match, 1 = no match) mdq only processes CommonMark Markdown; never apply it to AsciiDoc, RST, HTML, or other formats Use --output json when piping to jq or other structured tools Match selectors to the Markdown element type, not text content alone Use regex (/pattern/i) for case-insensitive matching; use unquoted text only for simple case-insensitive single-word lookups Identify the target Markdown elements and their location Identify the element type (heading, list, task, code block, link, etc.) Determine the required scope (full document or within a section) Choose the output format (markdown, json, plain) based on downstream use Construct and refine the mdq selector Write the primary selector matching the target element Add pipe-chained parent selector if scope must be restricted Add output flag if format other than Markdown is needed Verify the output matches the expected content Run against a sample file and inspect output Use --quiet and check the exit code (echo $status in fish, echo $? in bash) to confirm match behavior in scripts Adjust selector if over-matched or under-matched

<error_escalation inherits="core-patterns#error_escalation"> No matches found (exit code 1 in --quiet mode) Unexpected output format or extra content extracted Wrong content extracted; selector matches unintended elements mdq binary not found or not installed </error_escalation>

<related_agents> Locate Markdown files in the codebase before querying them Use extracted content to generate or update documentation </related_agents>

Verify the target file is CommonMark Markdown before invoking mdq Use --quiet (-q) for boolean match tests in automated pipelines Keep selector guidance evidence-based: test selectors against sample files before recommending Applying mdq to non-CommonMark formats (AsciiDoc, RST, HTML) Parsing stdout to detect match presence; use exit codes instead Broad document-wide child selectors when a parent section is the actual intended scope

<related_skills> General documentation authoring and structure Finding and querying files in a codebase </related_skills>