From notation-skills
ユーザーが指定したドキュメント(Markdown・テキスト・仕様書・設計書・README・議事録・PRD 等)を読み取り、 内容の構造・論点・関係を、固定ルールの DSL `document-map v1` テキストに落とす Skill。 Turn a document (Markdown, spec, design doc, README, meeting notes, PRD) into a fixed-grammar `document-map v1` DSL — generation only, no drawing. タイトル・主要セクション・重要概念・要件・決定事項・未決事項・リスク・関係者・外部依存と、 それらの関係を、意味層(ノード・エッジ)とレイアウト層に分けて出力する。深度(0/1/2)で 大きさを制御し、まず粗く、必要なら対象セクションを絞って深掘りする。全文要約はしない。 次のような発話で起動する: 「このドキュメントを図解して」「この仕様書を構造化して」「この Markdown を図にしたい」 「この PRD の論点マップを作って」「この議事録を関係図にして」「この設計書の構成を可視化して」 「添付ファイルを document-map DSL にして」「この要件定義の構造を地図にして」「ドキュメントの論点を整理して図に」 「README の全体像を図解」「会議メモの決定事項と宿題を関係図に」「この章だけ詳しく構造化して」。 出力は必ず `# document-map v1` で始まるテキスト。 禁止: DSL を出さずに Mermaid / SVG / HTML など図を直接生成しないこと(描画は `notation-render` の役割)。 ドキュメントの全行・全項目を網羅して詰め込まないこと(重要なものへ圧縮する)。リポジトリ解析はしないこと (それは `repo-map-notation`)。
How this skill is triggered — by the user, by Claude, or both
Slash command
/notation-skills:document-map-notationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
この Skill の仕事は**ただ 1 つ**——指定されたドキュメントを読み、内容の構造・論点・関係を `document-map v1` という固定文法の **DSL テキストに変換すること**。HTML の座標規約は扱わない(それは [notation-render](../notation-render/SKILL.md))。図そのものも描かない。**出力は常に `# document-map v1` で始まるテキスト**である。
document-map v1 DSLこの Skill の仕事はただ 1 つ——指定されたドキュメントを読み、内容の構造・論点・関係を document-map v1 という固定文法の DSL テキストに変換すること。HTML の座標規約は扱わない(それは notation-render)。図そのものも描かない。出力は常に # document-map v1 で始まるテキストである。
設計の土台(なぜ DSL を正本にするか、意味とレイアウトを分けるか)は notation-core を参照。document-map v1 の正式文法・検証コードは references/grammar.md が正本。
リポジトリ構造の地図化は責務外(それは repo-map-notation)。ここはドキュメントの内容だけを扱う。
notation-render に渡す。repo-map-notation の責務)。ユーザーが指定したドキュメントファイル、または貼り付けた本文。Markdown・プレーンテキスト・仕様書・設計書・README・議事録・PRD・添付ファイルなどを想定する。
depth は地図の粒度。大きいドキュメントほどまず粗く。
| depth | 粒度 | 主なノード種別 | こんなとき |
|---|---|---|---|
| 0 | ドキュメント全体の俯瞰 | document / section(+ actor / external) | 主要テーマと大きな構成だけ見たい |
| 1 | セクション・主要概念・決定・未決 | section / concept / decision / open-question(+ risk / actor / external) | 標準。構成と論点の地図 |
| 2 | 特定セクションの詳細 | requirement / concept / open-question / risk | 範囲を絞った1 セクションの深掘り(論点・要件・依存) |
迷ったら depth 1 から。深掘りは「ドキュメント全体を depth 2 にする」のではなく「対象セクションを絞って depth 2 にする」。詳しくは references/scope-and-depth.md。
DSL を書き始める前に、次をユーザーと合意(自明なら明示して進む)。
decides / depends-on / raises・mitigates / owns / conflicts-with …)。ドキュメントを読み、地図の素を集める。全行を均等に拾わない——重要なものを選ぶ。
集めた素を、読める地図の大きさに畳む。
contains で作る(document → section → concept …)。論点・担当・リスクなどは破線の横断辺(owns/raises/decides/mitigates/depends-on/references/conflicts-with)でつなぐ。抽象化したノード・エッジを DSL にする前に、どの「ビュー」で見せるかを 1 つ決める。同じ閉じた文法でも、選ぶ kind/relation・focus・@layout の使い方で地図は別物になる。ここを飛ばすと、毎回「document → section → concept のただの目次」に無意識に落ち、STEP 0 で決めた「何が分かれば成功か」に答えない地図になる。
decides/owns/raises/conflicts-with 等を主役にするビューを意図的に検討する。kind と relation の部分集合を絞る。focus の当て先も合わせる。contains 以外はランクに効かないので、目次順以外の並び(決定ステータス/リスク深刻度/担当レーン)は必ず @layout(rank=/group=)で作る。@meta depth を確定する。depth と各ノードの粒度が整合するよう調整(例: depth 0 に requirement / decision を混ぜない)。深掘り要求なら対象セクションへ source と範囲を絞る。完全な document-map v1 テキストを出力する。文法は references/grammar.md。出力前に自己検証(下記)を必ず通す。
「このセクションだけ詳しく」と言われたら、全体を作り直さない。@meta source を対象セクションに、depth を上げ、その部分スコープだけの新しい DSLを全量で出す(原則「全量置換・範囲を絞る」)。
references/grammar.md の検証規則の要点。1 つでも引っかかれば直してから出す。
# document-map v1。セクションは @meta → @nodes → @edges →(任意)@layout の順。@meta に source / depth(0|1|2) / generated がある。focus を使うならそのノードが存在する。@nodes に定義済み(未定義参照ゼロ)。id の重複なし。自己ループなし。kind は { document, section, concept, requirement, decision, open-question, risk, actor, external } のみ。relation は { contains, explains, depends-on, decides, raises, mitigates, owns, references, conflicts-with } のみ。"..." で引用。ref(出典ロケータ)はラベル直後の唯一の裸トークン。@layout には rank= / group= 以外(意味情報)を入れていない。| ファイル | 中身 | いつ読む |
|---|---|---|
| references/grammar.md | document-map v1 の正式文法・内部モデル・検証コード(正本) | DSL を書く・検証する全ての場面 |
| references/scope-and-depth.md | depth 0/1/2 の選び方、ドキュメント類型別ガイド(PRD・仕様書・議事録・README・設計書) | STEP 0 で粒度・範囲に迷ったとき |
| references/view-patterns.md | 固定文法のまま「見せ方」を変える 8 つのビューパターン+設計意図 4 軸の AskUserQuestion テンプレ | STEP 0 で観点を確認し、STEP 3 でどのビューにするか選ぶとき |
| references/examples.md | ドキュメント → 出力 DSL 全文(depth 別の例) | 出力の形を確認したいとき |
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub hirokita117/notation-skills --plugin notation-skills