New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Querying Markdown

by oaustegard in oaustegard/claude-skills

Query, filter, and transform Markdown structurally with mq — a jq-like CLI for Markdown.

MITAuto-check passedDocuments & Office

Install Querying Markdown

skills CLI
$ npx skills add oaustegard/claude-skills --skill querying-markdown -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install oaustegard/claude-skills querying-markdown --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/oaustegard/claude-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/querying-markdown .claude/skills/querying-markdown && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
querying-markdown
GitHub stars
150
Used in
1 other repo
Token cost
~1.4k tokens
SKILL.md length
672 words
Files
4 (incl. scripts, references)
Skills in repo
69
Repo updated
First seen
Licence
MIT

At a glance

Query, filter, and transform Markdown structurally with mq — a jq-like CLI for Markdown.

  • Extract headings/sections/code-blocks/links from .md files
  • SKILL.md covers Before you use mq: is this…, Setup, Usage and Empirical findings, plus 1 more section
  • Runs Shell scripts from its folder; calls bash
  • Build a table of contents

What it does

Querying Markdown is an agent skill from oaustegard/claude-skills. Query, filter, and transform Markdown structurally with mq — a jq-like CLI for Markdown. Use to extract headings/sections/code-blocks/links from .md files, build a table of contents, pull code blocks of a given language, slice or reshape LLM prompt/output Markdown, or batch-transform docs. Triggers on "extract sections from this markdown", "get all the code blocks", "jq for markdown", "mq", or any structural query over Markdown that grep/Read can't do cleanly.

Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 5 other files, including scripts and reference files (for example `CHANGELOG.md`, `references/cheatsheet.md` and `scripts/install-mq.sh`).

It sits in Documents & Office, covering Markdown. The repository describes itself as: My collection of Claude skills. The licence is MIT.

When your agent uses it

  • Extract headings/sections/code-blocks/links from .md files
  • Build a table of contents
  • Pull code blocks of a given language
  • Reshape LLM prompt/output Markdown

Example prompts

  • “extract sections from this markdown”
  • “get all the code blocks”
  • “jq for markdown”
  • “/querying-markdown”

Requirements

  • Python 3
  • A Bash shell

What it can do on your machine

Read from SKILL.md and the folder at commit 6fc82b8. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Shell), which the agent can run.

    Shell commands in SKILL.md call:

    • bash

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Querying Markdown loads about 1.4k tokens when it runs, and up to ~2.5k if it reads all its reference files. Until then it costs about 121 tokens; SKILL.md has 672 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~121
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~2.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from oaustegard/claude-skills at commit 6fc82b8, republished under its MIT licence (© oaustegard). 672 words, ~1,418 tokens.

Download SKILL.mdSave it as .claude/skills/querying-markdown/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.
name
querying-markdown
description
Query, filter, and transform Markdown structurally with mq — a jq-like CLI for Markdown. Use to extract headings/sections/code-blocks/links from .md files, build a table of contents, pull code blocks of a given language, slice or reshape LLM prompt/output Markdown, or batch-transform docs. Triggers on "extract sections from this markdown", "get all the code blocks", "jq for markdown", "mq", or any structural query over Markdown that grep/Read can't do cleanly.
metadata.version
0.2.0

querying-markdown

mq is "jq for Markdown" — it parses a .md file into a node stream and lets you select, filter, and transform by structure (.h2, .code("rust"), .link) instead of by line-matching. Reach for it when the task is structural: "every H2 title", "all bash code blocks", "a table of contents", "strip the frontmatter". For plain substring search, grep is still the right tool; for code (not prose) structure, use tree-sitting.

Before you use mq: is this actually a structural task?

mq parses the whole document into a node tree before it answers, and that parse cost is real (see Empirical findings). Most "query a markdown file" tasks don't need it. Decide first, using the target — not the file type:

Your targetUseWhy
Lines with a fixed prefix — #/## headings, > quotes, - bullets, a leading line/verse numbergrep / awkLine-matching, not structure. grep is faster and already installed.
A substring anywheregrepmq adds nothing.
Code structure inside fences (ASTs, symbols, call sites)tree-sittingmq sees the fence, not the code inside it.
Language-filtered code blocks (.code("bash")); links as structured (text, url) (-F json '.link')mqgrep can't filter a fenced block by language without a brittle hand-rolled fence state machine.
Markdown→Markdown transforms that must emit valid Markdown — demote/promote headings, rebuild a TOC with anchors, in-place editmqsed doesn't know structure and will corrupt nesting/fences.

If your task lands in a grep/awk row, do not install mq — close this skill and use the line tool. Diagnosed 2026-06-04: a full-KJV smoke test queried books/chapters/verses (all line-prefix structure) with mq — ~3.3 s per query where grep is milliseconds, the same answers, and a grep post-filter still needed on top. Wrong-shape corpus; mq's selectors earn their parse cost only on the structural rows.

The judgment call is whether the case is actually line-prefix or only looks it. A heading is a prefix; a heading you want demoted with its subtree, or a match you must re-emit as valid Markdown, is structure — mq's row even when the match looks like a prefix.

Setup

mq is a single static binary, not preinstalled. Install on first use (idempotent — exits early if already present, ~1s, no build step):

bash
bash /mnt/skills/user/querying-markdown/scripts/install-mq.sh

This drops the pinned mq release into /usr/local/bin. Override the version with MQ_VERSION=vX.Y.Z.

Usage

bash
mq 'QUERY' file.md          # query a file
cat file.md | mq 'QUERY'    # query stdin
mq repl                     # interactive REPL — use to test syntax fast

A node stream flows left→right through |. Selectors (.h, .code, .link) pick nodes; functions (to_text, slugify, map, len) transform them. self is the current node.

bash
mq '.h2 | to_text()' README.md            # every H2 as plain text
mq '.code("python") | to_text()' file.md  # all python code blocks
mq '.h.level' file.md                     # heading depth per heading
mq -F json '.h2 | to_text()' file.md      # results as JSON
mq '.h2 | to_text()' file.md | wc -l      # count matches (reliable idiom)
Show full SKILL.md (274 more words)Show less

Empirical findings

Measured 2026-06-04 against a full public-domain KJV Bible (66 files, 4.28 MB).

Parse-bound, not query-bound. mq reparses the whole document on every invocation; latency tracks document size, not selector or match count. On the 4.28 MB file every query — whether it returned 66 matches or 32,418 — ran ~3.2–3.3 s (~1.3 MB/s); on a normal-sized doc it is single-digit ms. Never loop mq per query over a large corpus: extract once with -F json and work on the result, or accept a constant per-call parse tax.

Selectors return nodes, not your domain concepts. .h2 over the KJV returned 1,250 nodes — 1,184 chapter headings plus 66 eof markers the source appended per file, while single-chapter books emitted no chapter heading at all. .text also pulled heading text into the paragraph stream. A raw selector count is a node count; map it to your concept with an explicit predicate (e.g. grep -E '^[0-9]+ ' for verses) and check it against a known total before trusting the number.

An empty result is ambiguous. Zero output means either the selector matched nothing or mq never ran — a wrapper like time/env failed in dash, or a malformed heredoc swallowed the command. Re-run the bare mq 'QUERY' file.md before concluding a selector or function is broken. (Self-inflicted 2026-06-04: a time: not found shell error read as a to_text() defect; to_text() on code blocks works.)

Reference

Selector aliases, the built-in function library, table-of-contents and transform recipes, in-place-edit caveats, and CLI flags live in references/cheatsheet.md. Read it before writing a non-trivial query — the dialect is jq-like, not jq, so the function names differ. When unsure of syntax, mq repl gives instant feedback.

© oaustegard, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (scripts, references) in querying-markdown of oaustegard/claude-skills.

  • SKILL.md
  • CHANGELOG.md
  • references/cheatsheet.md
  • scripts/install-mq.sh

Open the folder on GitHubat commit 6fc82b8

Used in 1 other repository

We found 2 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in oaustegard/claude-skills, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Querying Markdown next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Querying Markdown compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Querying Markdown this skilloaustegard/claude-skills1501 repos~1.4kAutomated safety check: PassMIT
Markdown Article FormatterJimLiu/baoyu-skills26k7 repos~3.5kAutomated safety check: PassMIT
MarkitdownImCa0/just-laws78114 repos~3.2kAutomated safety check: NotesMIT
Obsidian MarkdownAtmosphere/atmosphere3.8k20 repos~1.3kAutomated safety check: PassApache-2.0
Gzh Designisjiamu/gzh-design-skill3.9k1 repos~2.2kAutomated safety check: PassAGPL-3.0
Crosspostingwasp-lang/wasp19k—~1.1kAutomated safety check: PassMIT

Similar skills

  • Markdown Article Formatter

    JimLiu/baoyu-skills

    Reformats plain text or Markdown articles with frontmatter, a title, a summary, headings, bold, lists and code blocks, and saves a separate formatted copy.

    26k GitHub starsUsed in 7 repos~3.5k tokens
    Documents & OfficeAuto-check passed

  • Markitdown

    ImCa0/just-laws

    Convert files and office documents to Markdown. An agent skill from ImCa0/just-laws.

    781 GitHub starsUsed in 14 repos~3.2k tokens
    Documents & OfficeAuto-check: notes

  • Obsidian Markdown

    Atmosphere/atmosphere

    Create and edit Obsidian Flavored Markdown with wikilinks, embeds, callouts, properties, and other Obsidian-specific syntax.

    3.8k GitHub starsUsed in 20 repos~1.3k tokens
    Documents & OfficeAuto-check passed

  • Gzh Design

    isjiamu/gzh-design-skill

    微信公众号文章排版引擎，将 Markdown 转换为可直接粘贴到公众号编辑器的 HTML。主题风格从 references/theme-index.md 注册的自定义主题库中选取，自动章节编号、关键词下划线标记、引言卡片、目录导航、代码块、图片/GIF、作者签名。支持 Markdown / Word(.docx) / PDF / 纯文本输入（非 Markdown…

    3.9k GitHub starsUsed in 1 repo~2.2k tokens
    Documents & OfficeAuto-check passed

  • Crossposting

    wasp-lang/wasp

    Crosspost Wasp blog articles (MDX) to DEV.to and Medium. An agent skill from wasp-lang/wasp.

    19k GitHub stars~1.1k tokensUpdated yesterday
    Documents & OfficeAuto-check passed

  • Review The Docs

    supabase/supabase

    Official

    Review Supabase docs changes locally in your supabase/supabase checkout — either an open PR (triage, classify, verify) or your own branch before opening a PR (local self-review).

    111k GitHub stars~4.6k tokensUpdated today
    Documents & OfficeAuto-check passed

More from oaustegard/claude-skills

All 69 skills in this repo

  • Bluesky Zeitgeist Sampler

    oaustegard/claude-skills

    Deprecated sampler that captures short windows of the Bluesky firehose, clusters trending terms and builds an HTML report; replaced by the browsing-bluesky skill.

    150 GitHub starsUsed in 1 repo~1.4k tokens
    Auto-check passed

  • Vega-Lite Interactive Charts

    oaustegard/claude-skills

    Builds interactive Vega-Lite charts from uploaded data: analyzes the fields, picks five to ten fitting chart types, and produces a React artifact with the data embedded inline.

    150 GitHub stars~2.1k tokensUpdated yesterday
    Auto-check passed

  • Single-File HTML Composer

    oaustegard/claude-skills

    Builds self-contained single-file HTML pages such as reports, decks, postmortems, flowcharts and prototypes from a small spec using a bundled Python composer and templates.

    150 GitHub stars~3.2k tokensUpdated yesterday
    Auto-check passed

  • Declauding

    oaustegard/claude-skills

    Rewrites model-sounding prose into plain technical writing and checks that every claim survives, for PR text, docs, commit messages and similar drafts.

    150 GitHub stars~5.2k tokensUpdated yesterday
    Auto-check passed

  • Forecasting Reverso

    oaustegard/claude-skills

    Zero-shot univariate time series forecasting using the Reverso foundation model (NumPy/Numba CPU-only inference).

    150 GitHub starsUsed in 1 repo~1.5k tokens
    Auto-check passed

  • Preact Developer

    oaustegard/claude-skills

    Guides building standards-based Preact apps with native-first choices, HTM syntax, import maps and vendored ESM, from single-file demos to larger builds.

    150 GitHub stars~4.6k tokensUpdated yesterday
    Auto-check passed

Categories

Questions about Querying Markdown

What does Querying Markdown do?

Query, filter, and transform Markdown structurally with mq — a jq-like CLI for Markdown. Querying Markdown is an agent skill from oaustegard/claude-skills. Query, filter, and transform Markdown structurally with mq — a jq-like CLI for Markdown.

When should I use Querying Markdown?

Querying Markdown fits situations like: extract headings/sections/code-blocks/links from .md files; build a table of contents; pull code blocks of a given language; reshape LLM prompt/output Markdown.

How do I install Querying Markdown in Claude Code?

Run `npx skills add oaustegard/claude-skills --skill querying-markdown -a claude-code`. Or copy the skill folder (querying-markdown in oaustegard/claude-skills) into .claude/skills/querying-markdown in your project. Claude Code loads it when a task matches its description.

How do I install Querying Markdown in Codex?

Run `npx skills add oaustegard/claude-skills --skill querying-markdown -a codex`. Or copy the skill folder (querying-markdown in oaustegard/claude-skills) into .agents/skills/querying-markdown in your project. Codex loads it when a task matches its description.

Can I use Querying Markdown in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add oaustegard/claude-skills --skill querying-markdown -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/querying-markdown, .gemini/skills/querying-markdown, .github/skills/querying-markdown and .opencode/skills/querying-markdown in your project.

What does Querying Markdown need to run?

Going by SKILL.md and its folder, Querying Markdown needs a shell for the scripts in its folder and the command-line tools its instructions call (bash). Our summary lists: Python 3; A Bash shell.

Does Querying Markdown access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Querying Markdown safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Querying Markdown use?

Querying Markdown is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Querying Markdown use?

About 1.4k tokens (SKILL.md is roughly 5.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 1.1k tokens, read only when the agent opens those files.

What are the alternatives to Querying Markdown?

Skills that share tags, products or a category with Querying Markdown: Markdown Article Formatter (JimLiu/baoyu-skills, 26k stars), Markitdown (ImCa0/just-laws, 781 stars), Obsidian Markdown (Atmosphere/atmosphere, 3.8k stars) and Gzh Design (isjiamu/gzh-design-skill, 3.9k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Querying Markdown?

oaustegard (a GitHub user) maintains it in oaustegard/claude-skills, which has 150 GitHub stars. The repository holds 69 skills in this directory. The repository was last updated on October 8, 2026.

Source: oaustegard/claude-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.