muqsitnawaz/mq

Overview

This skill provides a CLI called mq for efficiently querying Markdown files and directories to surface structure and targeted content. It minimizes unnecessary reading by letting you map document layouts, search for terms, and extract precise sections or code blocks. Use mq to reduce token usage and speed up exploration when working with documentation or knowledge bases.

How this skill works

mq inspects Markdown files and folders to produce a lightweight structural index (trees, previews, section boundaries, and metadata). You run queries like .tree, .search('term'), .section('Name') or .code('lang') and mq returns only the structure or the exact content you request. The outputs enter your working context so you can reason from focused snippets rather than entire documents.

When to use it

• Exploring unfamiliar documentation to quickly map file and section structure
• Locating precise sections or terms across many .md files without reading everything
• Extracting only needed content or code blocks to reduce token consumption
• Preparing focused context for an agent or model that requires concise inputs
• Auditing or indexing docs to build a navigation or summary

Best practices

• Start with mq <path> .tree to get a single canonical map of the territory
• Search across the repo with .search('term') before opening files to pinpoint locations
• Extract only the section or code block you need using .section(...) or .code(...)
• Avoid re-running .tree repeatedly; use the structure that has already entered your context
• Combine .tree('preview') or .tree('full') with targeted .section queries for efficient drilling

Example use cases

• Map a docs/ directory to identify which files contain API, auth, and examples
• Find every occurrence of "OAuth" across the project and extract the OAuth Flow section
• Pull all Python examples from a repository to build runnable snippets
• Extract YAML frontmatter to collect configuration metadata across markdown files
• Drill into a specific API endpoint section to supply minimal context to a model