--- name: markdive description: > markdive CLI を利用してMarkdownファイルを効率的に読むスキルです。 ファイル全体を読み込まず、構造把握 → 必要箇所の精読という段階的な手順で読み込んでトークンを節約します。 **Markdownファイルを読む際は常に**このスキルを使ってください。 --- # markdive 使い方ガイド markdive は Markdown ファイルを **段階的に** 探索するための CLI ツールです。 ファイルを丸ごと読み込む代わりに「構造確認 → 絞り込み → 精読」のワークフローで、 コンテキストの消費を最小化します。 ## インストール確認 ```bash # グローバルインストール済みか確認 markdive --version # 未インストールの場合は npx 経由で実行できる npx markdive --version ``` --- ## 基本ワークフロー ### ステップ 1 — 全体構造を把握する（`dive`） ```bash markdive dive # depth=2 で構造を表示（デフォルト） markdive dive --depth 3 # より深い階層まで表示 markdive dive --json # JSON形式で取得（プログラム処理に便利） ``` **出力例:** ``` 1: はじめに — このドキュメントの概要 1.1: インストール — npm install で導入できる 1.2: 設定 — 設定ファイルの書き方 2: API リファレンス — 全メソッドの説明 2.1: メソッド一覧 — 利用可能なメソッドの一覧 ``` 各行の形式: `: <タイトル> — <サマリー>` ### ステップ 2 — 気になるセクションを掘り下げる（`dive --path`） ```bash markdive dive --path 2 # セクション2 から depth=2 で探索 markdive dive --path 2 --depth 3 # さらに深く markdive dive --path 1.3 --json # JSON形式で取得 ``` `--path` を指定した場合、`--depth` は「起点からの相対深さ」になります。 ### ステップ 3 — 必要なセクションを全文取得する（`read`） ```bash markdive read --path 2.1 # セクション 2.1 とその子孫を全文出力 ``` **出力形式:** ``` --- markdive: source: spec.md path: 2.1 context: API リファレンス > メソッド一覧 --- ## メソッド一覧 本文...（子セクションも含む） ``` --- ## セクション ID の仕組み | 見出し | ID | |---------------------------|---------| | 1つ目の `# 見出し` | `1` | | その下の1つ目の `## 見出し` | `1.1` | | さらにその下の `### 見出し` | `1.1.1` | | 2つ目の `# 見出し` | `2` | --- ## 典型的な利用パターン ### パターン A: 大きな仕様書から特定機能を調べる ```bash # 1. まず全体を把握 markdive dive spec.md # 2. "認証" に関する章 (例: セクション3) を掘り下げ markdive dive spec.md --path 3 --depth 2 # 3. 必要な節だけ精読 markdive read spec.md --path 3.2 ``` ### パターン B: 章立ての確認だけで十分な場合 ```bash markdive dive README.md --depth 1 # トップレベルの見出しのみ ``` ### パターン C: 構造を JSON で受け取り、プログラムで処理する ```bash markdive dive spec.md --json | jq '.[] | {id, title}' ``` --- ## サマリーのカスタマイズ 見出しの直後に HTML コメントを置くと、dive 表示に使われるサマリーをカスタマイズできます。 ```markdown ## 認証フロー ``` コメントがない場合は本文の先頭 50 文字が自動使用されます。 --- ## よくある注意点 - **Setext 形式 (`===`/`---`) の見出しは非対応** — ATX 形式 (`# Heading`) のみ対象 - **フェンスコードブロック内の `#` は見出しと見なされない** — コードブロック中の疑似見出しは無視される - **`--path` の ID はゼロパディングなし** — `"1.2"` は OK、`"01.02"` は NG