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`）。

記法中心設計（Notation-first design / Mid Notation Pattern, MNP）の共通土台を提供する Skill。 Shared principles for notation-first design: keep a DSL as the single source of truth and split generation from rendering. リポジトリ図解に限らず「意味層を DSL として正本化し、生成（AI・人が編集）と 表現（描画）を分離する」設計の用語・原則・検証観を扱う。`repo-map-notation` と `notation-render` の 土台であり、初回や設計判断に迷ったときに参照する。 次のような発話で参照する: 「記法の設計原則を知りたい」「DSL と描画を分けたい」「中間記法で図解したい」 「MNP 的に状態をテキストで持ちたい」「記法中心設計とは何か」「DSL を正本にする設計にしたい」 「意味層とレイアウトを分けたい」「AI に決まった記法で出力させたい」「同じ入力なら同じ図にしたい」 「notation の共通ルールを決めたい」「新しい記法（DSL）を設計したい」「同期ループを設計したい」 「自由作図をやめて決まった記法にしたい」。 この Skill 自体は具体的な DSL 文法を定義しない（それは `repo-map-notation` の役割）。原則と用語のみを扱う。

notation（`repo-map v1` / `document-map v1` DSL）を、**DSL テキストだけ**を入力に、決定的に図へ変換する Skill。 Render a notation DSL (`repo-map v1` or `document-map v1`) into a deterministic diagram — input is the DSL text ONLY. 先頭行のバージョンで対応を分岐する（未知バージョンは描かず拒否）。 `parse → validate → layout → emit` の手順で、同じ DSL からは常に同じ図を出す。出力は HTML（既定・単一ファイルの インタラクティブ Viewer・クリック質問パネル付き・`data-*`＋凡例）、任意で Mermaid。色・フォント・配置は固定テーマと固定アルゴリズムで決まり、 実行ごとにブレない。 次のような発話で起動する: 「この DSL を HTML にして」「repo-map を描画して」「document-map を描画して」「notation を可視化して」「地図を HTML で見せて」 「DSL を図にして」「repo-map v1 をレンダリングして」「document-map v1 をレンダリングして」「この記法を絵にして」「構造図を HTML で出力」 「出力された DSL を描いて」「同じ DSL なら同じ図にして」「凡例つきの HTML プレビューで」。 禁止（重要・本文でも再掲）: 入力された DSL 以外（自然言語の要望・口頭のレイアウト・リポジトリの再走査）から 図を描かないこと。DSL が無ければ描かず、不足や矛盾は `repo-map-notation` に差し戻すこと。 同じ DSL から毎回異なるレイアウトを出さないこと。

`repo-map v1` から生成された HTML Viewer に、ローカル Claude Code 連携・プロンプトコピー・ Python ブリッジ起動手順を足して「対話できる地図」にする Skill。 Make a generated repo-map HTML viewer interactive: click a node, then ask local Claude Code about it — via a stdlib-only Python localhost bridge, or via prompt-copy fallback. 描画そのものではなく、生成済み HTML を使った理解補助・対話ビューアを担当する （描画は `notation-render`、DSL 生成は `repo-map-notation`）。 次のような発話で起動する: 「repo-map HTML をインタラクティブにしたい」「Claude Code と HTML Viewer をローカルでつなぎたい」 「Python ブリッジを使って Claude Code に質問したい」「生成済み repo-map HTML からコード理解を深めたい」 「プロンプトコピー方式または localhost bridge 方式で使いたい」「図のノードをクリックして質問したい」 「ローカルで repo-map を見ながら Claude に聞きたい」。 完全にローカル用途（外部サーバ・社内 Git にアップロードしない）。Node.js 不使用、Python 標準ライブラリのみ、 裏側は `claude` CLI。任意コマンド実行はさせない。

巨大なリポジトリの構造を、固定ルールの DSL `repo-map v1` テキストに落とす Skill。 Turn a (possibly huge) repository into a fixed-grammar `repo-map v1` DSL — generation only, no drawing. ディレクトリ・パッケージ境界・代表的な依存関係を読み取り、認知負荷を下げる「地図の素」を 意味層（ノード・エッジ）とレイアウト層に分けて出力する。スコープ（root）と深度（0/1/2）で 大きさを制御し、まず粗く、必要に応じて範囲を絞って深掘りする。 次のような発話で起動する: 「このリポジトリを図解して」「アーキテクチャ地図を作って」「依存関係を DSL にして」 「モノレポの構造を可視化したい」「コードベースの全体像が欲しい」「repo-map を作って」 「構造をテキストで持ちたい」「どのパッケージが何に依存しているか地図にして」 「オンボーディング用の構造図を」「認知負荷を下げる地図がほしい」「この範囲を深掘りした地図に」。 出力は必ず `repo-map v1` テキスト。 禁止: DSL を出さずに Mermaid / Figma など図を直接生成しないこと（描画は `notation-render` の役割）。 リポジトリの全ファイルを列挙して DSL に埋め込まないこと（package / module 粒度に抽象化する）。