コンテキスト消費を抑える！Agent Skillsで実現するMarkdownファイルの段階的参照
1. はじめに
1.1 目的
Agent Skillsを活用したMarkdownファイルの段階的参照方法の紹介です。コンテキスト消費を抑えながら、効率的にMarkdownファイルを扱うためのテクニックを紹介します。
1.2. 読者対象と前提知識
- Agent Skillsの概要を把握されている方
- Terminalの操作に慣れている方
- Markdownの基本的な知識がある方
2.Agent Skillsの段階的開示とは何か
2025年、Agent Skillsの仕様が公開・オープン化されましたね。
Agent Skillsの段階的に情報を開示して、コンテキスト消費をコントロールするのは、
すごくいい考えだと思います。
引用元: Claude Docs - Agent Skills
Skillsの仕組み
SkillsはClaudeのVM環境を活用して、プロンプトだけでは不可能な機能を提供します。Claudeは仮想マシンで動作し、ファイルシステムアクセスを備えており、Skillsは指示、実行可能コード、参考資料を含むディレクトリとして存在し、新しいチームメンバー用に作成するオンボーディングガイドのように整理されています。
このファイルシステムベースのアーキテクチャは、段階的な情報開示を実現します。Claudeは事前にコンテキストを消費するのではなく、必要に応じて段階的に情報を読み込みます。
特に、ローカルLLM(SLM)の多くのモデルは、コンテキストウィンドウが狭いので、
段階的な情報開示で処理していく仕組みは重要です。
3.ツリーベースの構造ナビゲーションを備えたTUI-Markdownビューアtreemdの紹介
3-1. TUI
昨今、Terminal上で、Claude Codeや、CodexなどAIエージェントを利用しており、
Markdownを日々書かせたり、読んだりする訳ですが。
Markdownをプレビューして読むときは、IDEなりブラウザを開く必要があり、TailscapeなどのVPN経由でTerminalから読むときはIDE/ブラウザがなく、不便さを感じていました。
見つけました、treemdです。まだまだSTARも少ないですが便利です。
以下のスクリーンショットのように、Terminal上でMarkdownプレビューを参照することができます。また、vimと同じキー操作も備えているのも良い点です。
3-2. CLI
TUIだけではなく、CLIモード(非対話型)もサポートされており、
見出しだけを抜き出したり、指定したセクションだけを表示することもできます。
見出しのツーリ構造表示
treemd --tree README.md
結果：
├─ ## ✅ できること
├─ ## 📥 想定入力
├─ ## 📤 出力形式（概要）
├─ ## 💡 使い方例
├─ ## 📦 事前準備 - treemdコマンドの ダウンロードとインストール
├─ ## 📦 本Skillのインストール方法
├─ ## ⚠️ 注意
├─ ## 🗂️ ファイル構成
└─ ## 謝辞
選択し見出し＋本文(セクション)の内容の表示
treemd -s "謝辞" README.md
結果：
## 謝辞
- [treemd](https://github.com/Epistates/treemd.git) 作者の @Epistates さんに感謝します。
このCLIモードが良いのは、特別な仕組みがなくても、treemdコマンドさえあれば、
Markdownの見出しをインデックスとして扱って、特定の文章のみを参照できる点です。
treemd以外にも同様のことができるコマンドはあるかもしれませんが、筆者が探した限りはtree表示はサポートしていても、セクション抽出をサポートしているコマンドを見つけることができませんでした。TUIを含まないCLIモードだけのツールを開発するのも良いかもしれません。
3-3. インストール方法
treemdはRUSTで開発されており、cargoコマンドでインストールすることができるようになっています。
cargo install treemd
cargoコマンドを未インストールの場合、ReleaseページにMacOS/Windows/Linux向けのバイナリファイルが提供されているので、ダウンロードしてインストール/配置すると利用できます。
4. Markdownを段階的に参照するAgent Skill
4-1. markdown-reader-skillの紹介
treemdコマンドのCLIモードの2つのオプションを組み合わせることで、
Markdownファイルに関しても、段階的に参照して、コンテキストの消費を抑えるAgent Skillを作ることができると考えました。
SKILL.mdは非常にシンプルで以下の手順を踏むように書いているだけです。
※ md-index.pyの内容は4-3項に記載しています
## 基本手順（段階的読み込み）
1. 見出しツリーを表示する
`md-index.py --tree path/to/doc.md`
2. 読みたい見出し名を正確に選ぶ
3. セクションを抽出する
`md-index.py --section "見出し名" path/to/doc.md`
例えば、Codexに以下のようなプロンプトを与えると、このSkillが動作します。
$markdown-reader-skillを使って、README.mdの概要を教えてください。
このプロンプトにより、Codexはまずtreemd --tree README.mdを実行して見出しツリーを表示し、その中から「概要」という見出しを選び、次にtreemd --section "概要" README.mdを実行して概要の内容を抽出します。
4-2. 動作イメージ
以下、Codexで動作させた際のイメージ図です。
Skillを利用することで、Markdown全体をコンテキストに納めずに、
見出しを参照したあとに、特定のセクションを参照させることができています。
4-3. Scriptについて
treemd 互換のコマンド仕様（最低限）に合わせた、軽量Markdown CLI(Python)を同胞しています。
対応機能:
見出しツリー表示: --tree
セクション抽出: -s/--section（完全一致を優先、なければ部分一致）
Usage
# ツリー表示
./md-index.py --tree README.md
# セクション抽出（完全一致/部分一致）
./md-index.py -s "Installation" README.md
# stdin
cat README.md | ./md-index.py --tree
cat README.md | ./md-index.py -s "Usage"
5. 想定ユースケース
5-1. ローカルLLM(SLM)利用時にコンテキスト消費を抑える
始めに書いたように、コンテキストウィンドウが狭いSLMでは、
コンテキスト消費を抑えてMarkdownを参照できるのは良いと思います。
例えば、会議中にローカルLLMを使って議事録を参照したい場合、コンテキストウィンドウが狭いと、議事録全体を読み込ませることができません。しかし、treemdを使って必要なセクションだけを抽出してLLMに渡すことで、コンテキスト消費を抑えつつ、必要な情報を得ることができます。
例えば、フィジカルAIとか、エッジに近く小型のAIに対しての指示書(Markdown)を段階的に参照させるなども考えられます。
5-2. MarkdownファイルをRAGや辞書的に利用する
Strands Agents MCP Serverのように、マニュアル・ドキュメントをLLMに参照させたい場合、
"概要":"参照先のURL"のような索引をLLMに渡した後、ユーザの質問に合わせて概要からもう一段深い内容を参照先のURLから読み取るようなMCPサーバがよくあると思います。
RAG（検索拡張生成）は、チャンキング（Chunking）して、膨大なテキストデータを検索・処理しやすいように、小さな断片（チャンク）に分割してコンテキストウィンドウを節約しますが、
Vector DBが必要だったりと、やや大掛かりになります。
MCP Severや、Vector DBがなくても、コマンド一つでインデックスを効かせた
Markdownファイルの参照が実現できます。
5-3. 複数の設計書の間の同一章だけを参照させるのに利用する
Spec-driven developmentを用いてMarkdownファイルで複数の機能の設計書を同一章構成で作成した際に、複数機能✕章(例. 機能概要やシーケンス図)だけを比較して機能の重複や整合性を確認するようなことも、容易に実現することができます。
6. おわりに
Terminal上でMarkdownファイルをプレビューができるtreemdコマンドの紹介と、
treemdコマンドのCLIモードを活用した段階的なMarkdownファイルを参照するAgent Skillを紹介しました。
いつか訪れるコンテキストウィンドウのサイズ限界に備えて、Markdownファイル以外の段階的参照方法の検討、treemd以外のツールの手法も
検討していく必要があると思います。
7. 謝辞
- treemd 作者の @Epistates さんに感謝します。
Discussion