presentation

# presentation スキル Markdown ファイルを元に、**プレゼン開始時に全スライド分の「小さな Markdown 断片」をまとめて生成し、canvas を開くときに `open` の `input`（`slides`）へ一括で渡して**最初から presentation canvas 拡張機能に表示するスキルです（「スライド未読込」のプレースホルダーを挟みません）。**登録後のページ送り（次へ / 前へ / 一覧）は canvas のボタン・キーボード、対応環境では Surface Pen で完結**するので、agent はスライドを送るための `ask_user` ループを回す必要がありません。発表途中で内容やテーマを差し替えたいときだけ `load_deck` を呼びます。 ## 配布と導入 このファイルは任意導入の Skill です。プレゼン表示に必要な本体は `.github/extensions/presentation/` の Extension なので、まず Extension を導入してください。 公開リポジトリからユーザースコープへ導入する場合は、Copilot に次のように依頼します。 > `https://github.com/runceel/github-copilot-app-presentation/tree/main/.github/extensions/presentation` > から presentation canvas Extension をユーザースコープへインストールしてください。 再現可能な導入には `main` をリリースタグ（例: `v1.0.0`）または確認済みコミット SHA に 置き換えます。Extension はローカルコードを実行するため、導入前に差分とタグを確認してください。 Skill はプロジェクトの `.github/skills/presentation/SKILL.md` に置くか、利用者の Skill スコープへコピーします。配布上の注意（ZIP、Gist の単一ファイル上限、Mermaid の分割配布）は リポジトリの README と `THIRD-PARTY-NOTICES.md` を参照してください。 Extension だけを導入した環境では、同梱の `presentation_guide` ツールがこの Skill 相当の スライド書式・テーマ・Architecture DSL 情報を返します。presentation canvas 用の Markdown を作る前に必要な topic を取得してください。 ## いちばん大事な原則 ⚡ 1. **あなた（生成 AI）が書くのは、各スライド 1 枚分の「小さな Markdown 断片」だけ**です。HTML・CSS・テーマ・レイアウト・ページ番号・アニメーションは**すべて拡張機能側（marked）が担当**します。フル HTML を生成しないこと。 2. **全スライドの生成は、最初にプレゼンを依頼されたときに一度だけ**まとめて行い、`open_canvas` の `input`（`slides`）で一括登録します（発表途中で内容やテーマを変えるときだけ `load_deck`）。**ページ送りのたびに Markdown を生成し直さない**こと。 3. **ページ送りは canvas と入力デバイスの操作で完結**します。`load_deck` で登録したあとは、ユーザーが canvas 内の **◀ / ▶ ボタン**、**矢印キー（← →）**、**スライド一覧（☰）**で自由に移動できます。対応する Windows 環境では **Surface Pen の末尾ボタン**も使えます。agent が `ask_user` でページ送りループを回す必要はありません。 スライド 1 枚は、せいぜいこの程度の Markdown です: ```markdown --- deck: プレゼンのタイトル kicker: セクション名 page: 2 total: 6 --- ## スライドの見出し - 箇条書き **1** - 箇条書き 2 ``` この断片を**全ページ分まとめて配列**にして、`open_canvas` の `input`（`slides`）に渡せば、canvas を開いた瞬間に最初のスライドが表示されます。あとのページ送りは canvas 内の操作（◀ ▶・矢印キー・☰ 一覧）に任せられます。 ### AI が作るデッキと、利用者の 📂 インポートの使い分け 拡張機能には、**利用者が canvas の 📂 ボタンから workspace の Markdown を直接読み込む** 機能もあります（AI を経由しない機械的な分割）。次のように使い分けます。 - **📂 インポートで足りるケース**: 元 Markdown が既にスライド用に書かれている （空行の後の `---` でページが区切られ、必要な front matter が書かれている）。 この場合は利用者が自分で読み込めるので、AI が断片を作り直す必要はありません。 ページごとの front matter（Slidev 形式）と、ファイル先頭 front matter の継承 （`layout: title` は 1 枚目にだけ効く）に対応しています。 - **AI がデッキを組むケース（このスキルの本来の役割）**: 元 Markdown が 自然言語の文章（段落主体）で、見出し＋箇条書きへの**要約・整形が必要**なとき。 ページ分割が意図どおりでないときや、テーマ・レイアウトを指定して整えたいときも同様です。 利用者から「このファイルをプレゼンして」と依頼されたときは、従来どおり **このスキルの手順でデッキを生成**してください（📂 は利用者向けの導線であり、 AI がその代わりに使うものではありません）。 ## 仕組み ``` プレゼン開始時（1 回だけ） あなた → 全スライド分の小さな Markdown 断片の配列を生成 │ open_canvas("presentation", { input: { slides: [...] } }) ▼ 拡張機能が open 時にデッキを保持し、最初から先頭スライドを表示 ページ送り（canvas 内で完結） ユーザー → ◀ / ▶ ボタン・矢印キー・☰ 一覧 を操作 │ canvas が拡張機能に index を送信（POST /navigate） ▼ 拡張機能が登録済みスライドを marked で HTML 化 → サニタイズ → テーマ適用 │ SSE ▼ ネイティブ canvas の iframe が自動更新（agent の操作不要） ``` - **全スライドは最初に 1 回だけ生成**して `open_canvas` の `input` で登録します（発表途中の差し替えは `load_deck`）。以降のページ送りは canvas 側が担当するため、**Markdown の再生成も agent の操作も不要**です。 - レンダリング（HTML 化・装飾・ページ番号・Mermaid 図・絵文字）と**ナビゲーション UI**は **すべて拡張機能側**が担当します。外部サーバーや `localhost` ポートは不要です。 - 同時に表示するデッキは 1 つ。1 人での発表を前提とします。 - 拡張機能は `.github/extensions/presentation/` にあります（project スコープ）。 ## 主なアクション > **プレゼンの開始は、`open_canvas`（`canvasId: "presentation"`）の `input` に `slides`（必要なら `index` / `theme` / `sourceName`）を渡してデッキごと開く**のが基本です。`sourceName` には元 Markdown ファイル名を渡してください。Canvas のプリンターアイコンから `<元ファイル名>.pdf` を保存できます。こうすると canvas を開いた瞬間に最初のスライドが表示され、「スライド未読込」のプレースホルダーを挟みません。下表のアクションは、開始後の操作・更新に使います。 | アクション | 用途 | | --- | --- | | `load_deck` | 登録済みデッキを差し替える / 再ロードする。`slides`（各スライド 1 枚分の Markdown 断片の配列）、任意の `index`（最初に表示する 0 始まりインデックス、既定 0）、任意の `theme`（デッキ全体の配色テーマ、`dark`/`light`/`microsoft`/`custom`、既定 `dark`）を渡す。**発表途中で内容やテーマを変える**ときに使う（開始時は通常 `open` の `input` で渡す）。 | | `goto_slide` | 登録済みデッキ内で表示スライドを切り替える。`index`（0 始まり）を渡す。範囲外は端に丸められる。**通常のページ送りは canvas 内で行われるため不要**だが、ユーザーがチャットで「3 ページ目に飛んで」のように特定ページを指定したときに使う。 | | `show_slide` | スライドを 1 枚だけ差し替える。デッキ未登録での単発表示や、その場限りの差し替え用。通常のプレゼンでは使わない。 | | `open_presenter` | 表示中のデッキを、canvas と同期された外部全画面ウィンドウで開く。Edge / Chrome / Chromium の app mode を使い、ページ位置・キーボード・Surface Pen 操作を共有する。Surface Pen の末尾ボタン 2 回押しでも起動 / 終了できる。 | | `close_presenter` | `open_presenter` で起動した外部プレゼン画面を閉じる。 | | `export_pdf` | 表示中のデッキを16:9 PDFへ書き出すAI用action。任意の `outputPath` はworkspaceからの相対 `.pdf` パス、省略時は `presentation.pdf`。Canvas のプリンターアイコンは `sourceName` から `<元ファイル名>.pdf` を自動保存する。任意の `theme`（`dark`/`light`/`microsoft`/`custom`）はPDFだけに適用し、canvas表示は変えない。1スライド1ページで、背景・画像・コード強調・Mermaidを含む。`show_slide` による現在ページの一時差し替えも反映する。 | | `reset` | スライドとデッキをクリアして待機表示に戻す。 | > `load_deck` / `goto_slide` は結果に `{ ok, version, index, total }` を返します（`goto_slide` は `changed` も返し、表示が実際に変わったかを示します）。`index` は現在表示中の 0 始まりインデックス、`total` は総スライド数です。 > `export_pdf` は `{ ok, path, total, theme, bytes }` を返します。PDFを書き出す前に、元Markdownが更新されている場合は最新の全スライドを `load_deck` で再登録してください。Canvas のプリンターアイコンは、元 Markdown のファイル名を `sourceName` に渡しておくと `<元ファイル名>.pdf` を workspace に保存します。 ## スライド断片のフォーマット 各スライド（`load_deck` の配列要素、または `show_slide`）に渡す Markdown は、先頭に **フロントマター**（`---` で囲んだ `key: value`）を置き、その下に**本文の Markdown**を書きます。フロントマターは任意で、使えるキーは次のとおり（すべて省略可）: | キー | 役割 | | --- | --- | | `deck` | フッター左に出すデッキ名 | | `kicker` | 見出し上の小さなラベル（セクション名など） | | `page` | 現在ページ番号（1 始まり）。`total` と両方あるときだけフッター右に表示 | | `total` | 総ページ数 | | `title` | ブラウザータブのタイトル（省略時は `deck`） | | `layout` | `title` は表紙、`section` はセクション区切り、`backcover` は背表紙、`center` は見出し＋本文をまとめて上下中央に置くレイアウト。`title` / `backcover` にはカスタムテーマの `theme.json` が反映される。通常スライドは省略（見出しも本文も上寄せ） | | `size` | コンテンツサイズ。`auto`（既定）/`normal`/`large`/`xlarge`。`auto` は余白の多い通常スライドだけを canvas が安全な範囲で拡大する | | `theme` | （任意・上書き用）このスライドだけ配色テーマを変える。`dark`/`light`/`microsoft`/`custom`。明示的な canvas の `theme` がある場合はそちらが優先 | | `theme-file` | `custom` 用。CSS カスタムプロパティだけを定義したファイルを、元 Markdown と同じフォルダーを基準にした相対パスで指定する（例: `./themes/brand/theme.css`）。同じフォルダーの `theme.json` は自動読込 | | `logo` | （`layout: backcover` のみ）背表紙左上の文字列。`theme.json` のロゴより優先し、空にすると非表示 | | `copyright` | （`layout: backcover` のみ）背表紙左下の著作権表示。`theme.json` の文言より優先し、空にすると非表示 | 本文では通常の Markdown が使えます（GFM 相当: marked + 表）: 見出し `#`/`##`/`###`、箇条書き `-`/番号付き `1.`、強調 `**太字**`/`*色付き*`、`` `コード` ``、コードブロック ` ``` `、引用 `>`、表 `|...|`、リンク、画像 ``、Mermaid 図 ` ```mermaid `、固定配置の構成図 ` ```architecture `、絵文字 `:rocket:` など。**HTML エスケープやタグ生成は不要**で、素の Markdown をそのまま書きます。 通常スライドの本文先頭にある H1/H2 は、PowerPoint のタイトル領域と同様にスライド上部へ 固定表示されます。先頭以外の見出しは本文に残ります。表紙・セクション区切り・背表紙は それぞれの専用レイアウトを維持します。 コードフェンスに `csharp` / `json` / `diff` などの言語名を付けると、同梱の highlight.js がシンタックスハイライトします。 > 注意: フッターに `page`/`total` を出す場合は、ページ送りのたびに `page` の値を更新すること。 ## テーマ（配色テーマ） スライドの配色は **dark / light / microsoft / custom** から選べます。テーマはデッキ全体に適用し、**明示的な canvas の `theme` > Markdown front matter > `dark`** の順で決まります。 | テーマ | 見た目 | | --- | --- | | `dark` | **既定**。落ち着いた紺色の背景＋明るいアクセントのダークテーマ | | `light` | 白基調の明るく中立なテーマ（特定ブランドに寄らない汎用ライト） | | `microsoft` | Microsoft / Fluent 配色の組み込みブランドプリセット | | `custom` | CSS カスタムプロパティでブランドや社内テンプレートを定義するテーマ | | `custom` | `themeFile` または front matter の `theme-file` で読み込む CSS カスタムプロパティ専用テーマ | カスタムテーマは自己完結したフォルダーに置けます: ```markdown --- theme: custom theme-file: ./themes/brand/theme.css --- ## ブランドテーマ ``` `theme.css` には `--bg: #101820;` のような CSS カスタムプロパティだけを書きます。セレクターや `url()` は使用できません。表紙背景・表紙/背表紙ロゴ・著作権表示が必要な場合は、同じフォルダーに `theme.json` と `assets/` を置きます。画像は `theme.json` 基準の `assets/...` 相対パスで指定し、テーマフォルダー外へは出せません。 > **どのテーマでも、デッキの末尾に背表紙（Closing logo slide）が自動で 1 枚追加されます。** 最終スライドが `layout: backcover` でなければ拡張機能が既定の背表紙を補います（すでにある場合は追加しません）。agent 側で背表紙を書く必要はありません。ロゴと著作権表示は `theme.json` または背表紙 front matter で明示したときだけ表示されます。 ### テーマの選び方（ユーザーのテイストから判定） プレゼンを依頼されたとき、ユーザーの言葉に**テーマに関わるテイスト**が含まれていれば、それに合うテーマを選んで `load_deck` の `theme` に渡します。判断の目安: - **custom** … ブランドカラーや社内テンプレートを指定する表現。 - **microsoft** … 「マイクロソフトっぽく」「Microsoft / Fluent / Office っぽい」「あの 4 色で」など、Microsoft らしさを示す表現。 - **light** … 「明るい感じで」「ライトで」「白基調で」「清潔感のある」など、明るい配色を示す表現。 - **dark** … 「ダークで」「暗めで」「黒っぽく」「クール / かっこよく」など、暗い配色を示す表現。 - **指定なし** … テーマに関する言及がなければ **`dark`（既定）** で進めます。 > どのテーマか迷うとき、または複数のテイストが混ざるときだけ、`ask_user` で選択肢（dark / light / microsoft / custom）を尋ねます。明確なテイストがあるなら尋ねずにそのテーマで進めます。 > 発表の途中で「ライトにして」などテーマ変更を頼まれたら、`load_deck` を同じ `slides` と現在の `index`、新しい `theme` で呼び直せば、内容はそのまま配色だけ切り替わります。 ## 図（ダイアグラム）と画像 ### 図: Mermaid 記法 ` ```mermaid ` のコードフェンスに Mermaid 記法を書くと、アプリが図（SVG）として描画します。フローチャート・シーケンス図・クラス図・円グラフなどが使えます。 ````markdown ```mermaid flowchart LR A[企画] --> B[実装] --> C[発表] ``` ```` - Mermaid.js は拡張機能に**同梱**（`.github/extensions/presentation/vendor/`）。オフラインでも描画されます。 - 記法に誤りがあってもスライドは**空白になりません**。エラー表示と他の本文はそのまま表示されます。 ### 図: Architecture JSON DSL ` ```architecture ` は、ノードの座標・サイズ・コンテナ・重なりを固定して再現したい プレゼン資料向けの構成図です。`version: 1`、`canvas`、`elements`、`node`、 `group`、`connector` の詳細と完全な例は `.github/extensions/presentation/README.md` を参照してください。 **DSL v1 は安定版（stable）で、v1 として受理された文書は以後も v1 として受理されます。** ピクセル単位の描画結果は保証対象外なので、重要な資料では PDF 出力を事前確認してください。 group の `layout` は `row` / `column` / `grid` / `layered`（`layered` は `direction` に `down` 既定 / `right`）、node の内蔵 `icon` は `cloud` / `database` / `api` / `user` / `server` / `analytics` / `browser` / `mobile` / `network` / `queue` / `shield` の 11 種、 connector の port は `auto` 既定 / `top` / `right` / `bottom` / `left` を使えます。 外部 URL や任意 SVG は指定しません。内蔵アイコン以外を使いたいときは、リポジトリ直下の `assets/` に画像を置いて `icon: "assets/foo.svg"` で参照します（**先頭スラッシュなし**。 Markdown 画像の `/assets/...` とは書式が違うので注意。`.svg` / `.png` / `.webp` / `.jpg` / `.jpeg` のみ、`..` と非 ASCII のファイル名は拒否されます）。 同じ port から分岐する connector は自動 lane で分離され、orthogonal routing は node と既存 connector の重なりを避ける候補を優先します。複雑な経路だけは `routing: "polyline"` と `points` で明示します。 自動レイアウトが必要なら Mermaid、資料上の配置を厳密に保ちたいなら Architecture DSL を使います。不正な JSON や参照は図の場所にエラー表示され、他の本文は残ります。 DSL の機械可読な JSON Schema は `.github/extensions/presentation/schema/architecture-v1.schema.json` にあります。 図を単体ファイルとして書くときは相対パスの `$schema` を付けるとエディターで補完・検証が 効き、その JSON をそのまま ` ```architecture ` フェンスへ貼り付けられます。 ### 画像 - **リモート URL**: `` をそのまま書けます。 - **ローカル画像**: リポジトリ直下の **`assets/`** フォルダーに画像を置き、`` で参照します（サブフォルダー・SVG・日本語ファイル名も可。`/assets/...` の絶対パスで参照すること）。 ## プレゼン開始の手順 ### 1. 対象 Markdown を特定する ユーザーの指示（例: 「`slides.md` に従ってプレゼンして」）から元 Markdown ファイルのパスを決めます。指定が無ければリポジトリ直下の `slides.md` を既定とし、無い場合は `ask_user` でパスを尋ねます。 ### 2. Markdown をスライド配列にパースする - **区切り**: 行頭から行末まで完全に `---`（ハイフン 3 つのみ）の行をスライド区切りとします。 - **コードフェンス内は無視**: ` ``` ` で囲まれたブロック内の `---` は区切りにしません。 - **先頭の front matter**: ファイル先頭が `---` で始まる YAML ブロックはデッキ設定（任意）でありスライドではありません。読み飛ばします。 - **スライドサイズ指定**: 各スライド本文の先頭に `<!-- slide-size: large -->` があれば表示用ディレクティブとして扱い、本文から除いて生成する断片の front matter に `size: large` を設定します。値は `auto` / `normal` / `large` / `xlarge` です。 - 各スライドの前後の空白をトリムし、空スライドは捨てます。 - 各スライドの**タイトル**（一覧表示用）は、最初の見出し行、無ければ最初の非空行の先頭 40 文字程度を使います。 - デッキ全体のタイトルは、先頭 front matter の `title`、無ければ最初のスライドの見出しを使います。 ### 3. 全スライドの Markdown 断片を一括生成する **ここがプレゼン開始時の主作業**です。パースした各ページについて、「スライド断片の生成」のルールに従って**全ページ分の Markdown 断片を生成**し、表示順に並べた**配列**を作ります。各断片には `page` / `total` のフロントマターを正しい値で埋め込みます（`total` は総スライド数、`page` はそのスライドの 1 始まり番号）。元 Markdown に `slide-size` ディレクティブがあるページは、その値を `size` として引き継ぎます。指定がなければ `size` は省略し、canvas の `auto` 判定に任せます。 このとき、ユーザーの依頼に**テーマに関わるテイスト**があれば「テーマの選び方」に従って `dark` / `light` / `microsoft` / `custom` のどれかを決めておき、次の手順 4 で `open` の `input` の `theme` に渡します（言及がなければ `dark`）。テーマは各スライドの front matter には書かず、デッキ単位で 1 回指定します。 > この一括生成は**プレゼン開始時に一度だけ**行います。あとのページ送りでは断片を作り直しません。 > スライド一覧（☰）のタイトルは canvas 側が各断片から自動生成するため、agent が `titles` を会話メモリに保持する必要はありません。現在位置の管理も canvas（拡張機能）が行います。 ### 4. canvas をデッキごと開く（最初からスライドを表示） 手順 3 で作った配列を、**`open_canvas` の `input` に渡してネイティブ canvas を開きます**。これで canvas を開いた瞬間に最初のスライドが表示され、「スライド未読込」のプレースホルダーを挟みません。`open_canvas` を 1 回呼ぶだけです: - `canvasId`: `"presentation"` - `instanceId`: `"presentation"` - `input`: `{ "slides": ["<スライド1>", "<スライド2>", ...], "index": 0, "theme": "dark" }`（`index` は省略可・既定 0、`theme` は省略可・既定 `dark`。手順 3 で決めたテーマを渡す） URL の指定は不要で、拡張機能が表示先を用意します。外部サーバーの起動や生存確認は不要です。これでデッキが登録され、最初のスライドが canvas に表示されます。**以降のページ送りは canvas 内の操作で完結する**ので、agent は通常それ以上の操作をしません（次の手順 5 を参照）。 > 既に開いている canvas を前面に出したいだけのとき（再フォーカス）は、`input` を**付けずに** `open_canvas` を呼びます。同じデッキで `input` を付け直しても拡張機能側で現在のスライド位置は維持されますが、無用な再登録を避けるため再フォーカス時は `input` を省略してください。 > ⚠️ **`input` は JSON です。** 本文に半角ダブルクォート `"` やバックスラッシュ `\` を含めるときは、必ず `\"` / `\\` にエスケープしてください（下の「JSON 入力の注意」を必ず参照）。素の `"` が 1 つでも混ざると `open`（デッキ登録）全体が失敗します。 ### ⚠️ JSON 入力の注意（最重要・デッキ登録失敗の最頻出原因） `open` の `input`（`slides` 配列要素）や `invoke_canvas_action` の `input`（`load_deck` の `slides` 配列要素、`show_slide` の `markdown`）は、**JSON 文字列として渡されます**。つまり、あなたが書く**スライド本文の Markdown はすべて JSON の文字列の中身**になります。ここで JSON のエスケープを誤ると、`input` が壊れて正しく渡らず、次のようなエラーで**デッキ登録ごと失敗**します。 ``` CanvasInputInvalidError: Invalid input for action "load_deck" ... (root): must be object ``` このエラーは「スキーマが違う」ように見えますが、**実際の原因はほぼ常に本文中の未エスケープ文字で JSON が壊れたこと**です。次のルールを必ず守ってください。 - 本文中の **半角ダブルクォート `"` は `\"` にエスケープ**する。 - 本文中の **バックスラッシュ `\` は `\\`** にする。 - **改行は `\n`** で表す（実際の改行文字を文字列内に直接入れない）。 #### 推奨: そもそも素の `"` を本文に書かない 日本語のプレゼンでは、強調や引用に**素の半角 `"` を使わず**、次のいずれかにすると見た目も良く、エスケープ事故を根本から防げます。 - かぎ括弧 `「」` / 二重かぎ括弧 `『』` - 曲線引用符（全角）`“ ”` **Before（壊れる・NG）** — 本文に素の `"` が入っている: ```json { "slides": ["## 方針\n\n- サーバーを\"信頼の境界\"にする"] } ``` ↑ この `"信頼の境界"` の `"` を**そのまま**書くと JSON が壊れて失敗します。 **After（OK）** — 素の `"` を `「」` に置き換える（推奨）か、`\"` にエスケープする: ```json { "slides": ["## 方針\n\n- サーバーを「信頼の境界」にする"] } ``` ```json { "slides": ["## 方針\n\n- サーバーを\"信頼の境界\"にする"] } ```