Skip to content

docs: add agent skill and tql reference documentation for treemd - #61

Merged
nicholasjpaterno merged 1 commit into
Epistates:mainfrom
wei840222:main
Jul 29, 2026
Merged

docs: add agent skill and tql reference documentation for treemd#61
nicholasjpaterno merged 1 commit into
Epistates:mainfrom
wei840222:main

Conversation

@wei840222

Copy link
Copy Markdown
Contributor

Summary

This PR adds an AI Agent Skill specification and a concise tql (treemd query language) reference guide under the skills/treemd/ directory.

As LLM-based coding agents and automation workflows increasingly rely on CLI tools to navigate large markdown files, having an explicit skill definition enables agents to use treemd efficiently for structural inspection and target extraction without loading entire files into LLM context.

Changes Included

  • Added skills/treemd/SKILL.md:
    • Establishes guidelines for structural navigation (overview --tree/--count/-l, locate --filter, extract -s) and query navigation (tql).
    • Clarifies CLI vs. TUI usage boundaries (TUI reserved for interactive human sessions).
    • Documents exact-match behavior for -s, stdout/stdin streaming, --query-output options, integration patterns (jq pipeline usage), and error handling exit codes.
  • Added skills/treemd/references/query-language.md:
    • Summarizes tql syntax, element selectors (.h, .code, .link), filters, hierarchy operators (>, >>), collection/string/filter/aggregation functions, and output formats.

Motivation & Benefits

  • Provides standardized skill context for AI coding assistants (e.g., Gemini, Claude, Cursor, Agentic frameworks) to leverage treemd out-of-the-box.
  • Serves as a quick reference guide for users looking for concise tql query snippets.

Checklist

  • Skill metadata complies with YAML frontmatter conventions (name, description, version).
  • All commands and tql queries verified against treemd version 0.6.0.
  • Markdown paths and file references verified.

@nicholasjpaterno
nicholasjpaterno merged commit f132ad6 into Epistates:main Jul 29, 2026
7 checks passed
@nicholasjpaterno

Copy link
Copy Markdown
Contributor

@wei840222 thanks for taking the time to put this together, it's a great addition to treemd. Most people don't realize how valuable treemd can be with AI agents - particularly for large markdown files. I may add a note to the readme

@wei840222

Copy link
Copy Markdown
Contributor Author

Thank you.
This project solves the issue where AI agents often get lost within the complex structures of large files—particularly Markdown files exceeding a thousand lines—when reading them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants