pptx-presentation-builder

# pptx-presentation-builder PowerPoint の資料を作るスキル。xlsx-report-builder の pptx 版で、考え方とサブコマンドは同じ。**基本の使い方は、依頼のフレーズから流れ（フロー）を選んで進める**こと。個々のサブコマンドを直接呼ぶ使い方は、オプション（[サブコマンド一覧](#サブコマンド一覧個別に呼ぶ場合)）。 - テンプレート（体裁の決まった .pptx、前の案件の資料）がある → スライドのスタイル・図形をそのまま使い、内容を流し込む - テンプレートが無い → JSON スペックから新規に生成する（凝った体裁の資料を一から作るなら presenter スキル） pptx ならではの約束が 3 つある。 1. **図は pptx の図形で作る**。テンプレートやサンプルの図（矩形・角丸・丸・矢印線・ブロック矢印）は、その図形を複製・移動して使い、画像にしない。新規生成でも、流れは図形とコネクタで描く 2. **サンプルと同じ粒度に収める**。文字の大きさ・図形の大きさ・間隔は変えず、データの量の方を合わせる。サンプルの文字数・項目数（`max_chars`・`max_items`）と、図形に収まる行数を超えると、`render` はどの欄を何字・何項目減らせばよいかを挙げて止まる。量を調整する（要約する・まとめる）のは LLM の仕事 3. **サンプルと同じ書きぶりにする**。スライドごとの趣旨（何を言うスライドか）と論理構成（タイトル・本文・図のつなぎ方）、資料全体の流れを定義に書き、データはそれに沿って書く。文末（です・ます／だ・である／体言止め）・1 文の長さ・数字と句読点の表記は `analyze` がサンプルから測り、違う文があると `render` が挙げて止まる パスはこの SKILL.md からの相対パス。コマンド実行前にこのディレクトリに `cd` すること。 ## 起動手順 スキル開始時に必ず実行する: ```bash cd .github/skills/pptx-presentation-builder uv sync ``` ## 使い方: フレーズ → フロー 依頼のフレーズから、次のどれかのフローを選ぶ。判断がつかないときは、まず「テンプレート（元にする資料）はありますか。ある場合、どこで作られたものですか」と聞く。 | # | 依頼のフレーズ（例） | フロー（→ は順に進む。【確認】はユーザーに確認する） | 使うサブコマンド | |---|----------------------|------------------------------------------------------|------------------| | 1 | 「このパワポに流し込んで」「この資料と同じ形式で作って」「前回の報告スライドを雛形にして」「他のプロジェクトの資料を元に作って」 | 出所を聞く【流用なら可否を確認】→ テンプレートの事実を読む → 図形ごとに 残す/流し込む/繰り返す/無視する を決める【確認】→ 定義を確定して検査 → データを用意（粒度に合わせて量を調整）→ 再構成 → 見て確かめる | `inspect`・`analyze`・`check`・`render` | | 2 | 「今月分も同じスライドで作って」「同じ形式でもう一度」（定義が確定済み） | データを用意 → 再構成（専用スクリプトがあればそれを実行）→ 確かめる | `render`（または専用スクリプト） | | 3 | 「この資料の内容を差し替えたい」「前の資料を直して出し直したい」 | 記入済みの資料からデータを取り出す → データを直す → 再構成 | `extract`・`render` | | 4 | 「スライドを足して」「テンプレートが更新された」「入れる欄を変えたい」 | 既存の定義を取り出す → 定義を直す【確認】→ 検査 → 書き出し直す／再構成。スライドの構成が変わったなら #1 に戻る | `export --from-script`・`check`・`render` | | 5 | 「毎回使えるスクリプトにして」「LLM なしで回せるように」 | 定義を確定して検査 → 専用の単体スクリプトを書き出す → 動作を確かめる | `check`・`export` | | 6 | 「スライドを作って」でテンプレートが無く、箇条書き・表・手順の図・並列の項目で足りる | データと構成を確認 → JSON スペックを組む → 生成 → 確かめる | `example`・`build` | | 7 | 「このpptxの構造を教えて」「どこが入力欄か調べて」「サンプルの値が残っていないか見て」 | テンプレートの事実を読む → 結果を要約して返す（生成はしない） | `inspect`（`analyze`） | - #1 の「流用」（他プロジェクトの資料）は、同じフローに流用の可否の確認を足す。値・メタデータを持ち越さない決めごと（`strict`・`keep`・`properties.scrub`）は、流用でなくても既定で入る - LLM が関わるのは、判断（図形の役割・定義）と、データの用意（量の調整を含む）まで。`check`・`render`・`extract`・`export` と、書き出した専用スクリプトは、決まった処理だけで動く - #2・#5 は、定義が確定していることが前提。無ければ #1 から ## フローの詳細: テンプレートへの流し込み（#1〜#5） 詳細は [references/template.md](references/template.md)。 ### 段の一覧 | 段 | 何をするか | 誰が | コマンド | |----|-----------|------|----------| | T0 | テンプレートの出所を聞く。他プロジェクトの資料なら、流用してよいか（社外秘・個人情報・権利）を確認する | LLM → ユーザー | — | | T1 | テンプレートの事実（図形・文字・大きさ・収まる量・図の並び・仮値の疑い・来歴）を読む | コマンド → LLM | `inspect` / `analyze` | | T2 | 図形ごとに 残す・流し込む・繰り返す・無視する を決め、スライドごとの趣旨・論理構成を書き、一覧をユーザーに確認してもらう | LLM + ユーザー | — | | T3 | 定義を確定し、整合と「テンプレートの値の残り」を検査する | コマンド | `check` | | T4 | データを用意する。趣旨・論理構成・文体に沿って書き、粒度（`max_chars`・`max_items`）に合わせて要約する・まとめる | LLM | — | | T5 | 再構成する。収まらない欄があれば、挙がった欄だけ T4 に戻って直す | コマンド（LLM なし） | `render` | | T6 | 同じ資料を繰り返し作るなら、専用の単体スクリプトにする | コマンド | `export` | | T7 | 出力を見て確かめる（画像にして見る） | LLM | — | ### T1: テンプレートの事実を読む ```bash uv run python scripts/pptx_builder.py inspect path/to/template.pptx # 判断用の事実（--json も可） uv run python scripts/pptx_builder.py analyze path/to/template.pptx -o def.yaml # 定義の下書き（自動検出） ``` `inspect` は、スライドごとに次を出す。 - 図形の id・名前・種類（プレースホルダー・矩形・角丸・丸・コネクタと矢印の向き・表・画像・グラフ・グループ）、位置と大きさ（cm） - 文字と段落の段（レベル）、**収まる量**（1 行の字数 × 行数、文字の大きさ）と、いま使っている行数 - **図の並び**（同じ大きさの図形が等間隔に並ぶもの。番号の丸・説明の文字も 1 つ分にまとめ、間の矢印も挙げる） - **仮の値の疑い**（`サンプル`・`〇〇`・`yyyy` など）と**注記の疑い**（`※`） - **来歴・持ち越しの注意**: 文書のプロパティ（作成者・会社名・タイトル）、プレビュー画像、ノート、コメント、非表示のスライド、外部へのリンク、グラフ・埋め込みのオブジェクト、マクロ `analyze` の下書きは確定ではない。判断は `inspect` の事実を読んだこちら（LLM）が行う。 ### T2: 図形ごとに、役割を決める | 役割 | 意味 | 定義での書き方 | 向く図形 | |------|------|----------------|----------| | 残す（keep） | テンプレートのまま出す | `keep` | `目的：` のようなラベル、ロゴの文字、固定の注記、フッター | | 流し込む（fill） | データの文字で置き換える（`null` なら空欄） | `texts`・`lists`・表の `cells` | タイトル・本文・箇条書き・宛名・日付、空の記入枠 | | 繰り返す（repeat） | 見本を、データの件数だけ複製する | スライドの `repeat`、表の `key`・`columns`、`diagrams` | 1 件 1 枚のスライド、表の行、図の並び（手順の箱と矢印・カード） | | 文書の値（doc） | データではないが、文書ごとに変わる値。文の一部だけでも差し替える | `texts` の `{text: "{文書.年度}年度 第{文書.四半期}四半期 報告"}`、ラベルの右の欄は `文書.作成日`、`properties` | 表紙のタイトルの年度・四半期、宛名の「○○ 御中」、見出しの「（2025年9月）」、フッターの表題、作成日・作成者・版 | | 無視する（ignore） | 出力に残さない | `clear`（文字だけ空に）、スライドの `drop`（スライドごと取り除く） | 記入例・使い方の説明・見本の 2 枚目以降 | 判断の目安: - **タイトル・宛名・フッターは、文字の中の可変の部分を見る**。「2025年度 第1四半期 報告」の年度・四半期は次の資料では変わるが、「報告」は変わらない。文全体をデータにせず、変わる部分だけを文書の値（データの `文書:`）にする。`analyze` は年度・四半期・年月・日付・期間・版・宛名を見つけて下書きし、確認の項目に挙げる。毎回同じ文字は `keep` に戻す。作成日・作成者・版などのラベルの右の値も `文書.` のキーになり、どのスライドでも 1 つの値が入る（xlsx-report-builder と同じ） - **同じ形のスライドが続く**（施策ごとに 1 枚など）→ 1 枚目を `repeat` の見本にし、残りは `drop`。`analyze` がそう下書きする（セクションはまたがない。どの見本でも同じ文字は残す）。形が同じでも中身の違うスライド（目次とまとめ、毎回同じ付録）を繰り返しにされたら、別のスライドか `keep` に直す - **表の最後の行（合計・小計）**は残し、値はデータに書く（`合計.件数` のような欄）。合計は計算しないので、足した値を書く - **図の並び**は、図形 1 つ分（箱 + 番号の丸 + 説明の文字）を `items` に、間の矢印を `connectors` に書く。データの件数だけ、見本の図形を同じ間隔で並べ直す（見本が中央寄せなら中央に）。見本の色が交互なら、交互のまま増やす。番号（`1`・`STEP 1`）は `$index` で振り直す - **ラベルに対する値は、残さない**。日付・宛名・作成者・版・顧客名は前の案件の実データ。流し込むか空にする - **データに書くのは、文書ごとに変わる値だけ**。どの行も同じ文字の列は `keep: true`、押印・承認・確認者の列は `clear: true`、見出しも値も無い列は定義に入れない - **表の見た目に頼る値は、データでは意味の分かる形にする**。○× の列は `完了: true` と書き、変換は定義（`map`・`when`・`part`）に任せる - **空の記入枠もキーを残す**（空のプレースホルダー） - 迷う図形は、決めずにユーザーに聞く。聞くときは、図形・候補の役割・理由を 1 行ずつ示す #### 文章の型を書く（趣旨・論理構成・文体） 見た目だけでなく、サンプルの書きぶりも写す。`inspect` の文字を読み、次を定義に書く（書き方は [references/template.md](references/template.md#文章の型趣旨論理構成文体)）。 | 単位 | 書くもの | 定義 | |------|----------|------| | スライド | 趣旨（そのスライドで言いたいこと）、論理構成（タイトルで論点を言い切る → 根拠を 3 つ、など） | `intent`・`logic` | | 欄 | 文末、1 文の長さ（`analyze` が測る。タイトルが言い切りか名詞止めか、箇条書きが体言止めか） | `ending`・`sentence_chars` | | 資料全体 | スライドの流れ（背景 → 課題 → 施策 → 効果、など）、数字と句読点の表記（表記は `analyze` が測る） | `style.logic`・`style.digits`・`style.punctuation` | - 趣旨は、スライドの見た目（箇条書き・表・図）ではなく、読み手に何を分かってもらうスライドかで書く。タイトルが論点を言い切る形（メッセージ型）か、話題の名前だけ（トピック型）かも見る - `analyze` が測った文末は、サンプルが仮の文や書き方の説明なら外す - 判断の一覧と一緒に、趣旨・論理構成もユーザーに見せる #### 前の文書の値・メタデータを持ち越さない `analyze` の下書きは、はじめから次の形になっている。外すのは、ユーザーが望んだときだけ。 1. **`strict: true`**。文字を持つ図形が、`texts`・`lists`・`keep`・`clear`・表・図のどれにも入らないまま残ると、`check` と `render` がスライドと図形の名前を挙げて止まる。挙がったものを、そのまま全部 `keep` に貼らない 2. **`properties.scrub: true`**。作成者・最終更新者・会社名・タイトルなどを空にし、プレビュー画像・カスタムプロパティ・コメントを取り除き、ノートを空にする（残すノートは `notes` にキーを書く）。与えたい値（`title: "第3四半期 報告"`）は同じ `properties` に書く 3. **グラフの値・埋め込みのオブジェクト・外部へのリンク・非表示のスライド**は、`inspect` が挙げるが、自動では消さない。ユーザーに見せて扱いを決める 決めたら、判断の一覧（図形 | 役割 | 理由）を**ユーザーに見せて確認してもらう**。確認前に定義を確定しない。 ### T3: 定義を検査する ```bash uv run python scripts/pptx_builder.py check --def def.yaml # テンプレートは定義の template（定義ファイルからの相対パス）から読む。--template で上書き ``` 整合（スライド・図形の名前・表の見出し・図の items）を確かめ、雛形データで試しに再構成する。最後に、データの書き方と**収まる量**（`s2.points[]: 最大 3 項目・1 項目 18 字まで`）の一覧が出る。T4 はこの一覧を見て書く。 ### T4〜T5: データを用意して再構成する データは、スライドのキー（`s1`・`s2` …）ごとの欄を持つ JSON か YAML（[assets/template.data.example.yaml](assets/template.data.example.yaml)）。繰り返すスライドは配列。数値・事実を捏造しない。 `check` の一覧に出る趣旨・論理構成・文体に沿って書く。新しい内容は、資料全体の流れ（`style.logic`）の順に、趣旨の合うスライドへ入れる。どのスライドの趣旨にも合わない内容は、別のスライドに押し込まずにユーザーに聞く。 ```bash uv run python scripts/pptx_builder.py render --def def.yaml --data data.yaml -o out.pptx ``` 収まらない欄があると、次のように挙げて止まる（終了コード 1）。**フォントを小さくしたり、図形を広げたりしない**。挙がった欄の文章を要約する・項目をまとめる・図の段を統合する、のどれかでデータを直し、もう一度 `render` する。文体の違いは、その文をサンプルの文末・表記に書き直す。 ``` 収まらない値があります。テンプレートの粒度に合わせて、データの量を減らすか言い換えてください: スライド 2「Content Placeholder 2」(points): 5 項目。この枠に収まるのは 3 項目まで（2 項目減らすか、まとめる） スライド 5 図 flow1 1 つめ(label): 13 字。サンプルの粒度は 8 字まで（5 字減らす） スライド 3（s3[0]）「目的」(目的): 3 行になる。図形に収まるのは 1 行（1 行 約 30 字・14pt） サンプルの文体と違う文があります。定義の文体（ending・sentence_chars・style）に合わせて書き直してください: スライド 2「Content Placeholder 2」(points) 1 項目め: 「確認に時間がかかります」はです・ます調。サンプルはだ・である調 ``` - 量を減らせない内容（法定の記載・全件の一覧）なら、ユーザーに確認して、そのスライドに `overflow: split` を書く。上限を超えた分は、同じ形のスライドを続けて足す - 粒度の上限そのもの（`max_chars`・`max_items`）を変えるのは、ユーザーが望んだときだけ - `--allow-overflow` は、止めずに警告にする（下書きを見せるときだけ使う） データが大きくなるなら、ファイルを分けてよい。`--data` に複数のファイルかフォルダを渡すと、1 つにまとめて流し込む。繰り返すスライド・箇条書き・表の行・図の配列はファイルの順（フォルダなら名前順）につなぐ。同じ欄に違う値があると止まる。書き出した専用スクリプトも同じ。分け方は、枚数ではなく**スライドのまとまり**ごと。定義の `slides[].group` が同じスライドを 1 ファイルにし、無ければスライドごとに分ける。`analyze` は、PowerPoint のセクション（章）の名前を `group` に入れる。セクションで分かれない意味のまとまりは、下書きを読んで `group` を直す。`extract --split DIR` は、取り出したデータをこのまとまりごとのファイルに分けて書く。 ```bash uv run python scripts/pptx_builder.py render --def def.yaml --data 01-表紙.yaml 02-施策.yaml -o out.pptx uv run render_report.py --data data/ -o out.pptx # フォルダの中のデータファイルを名前順に ``` 記入済みの資料（前の案件の資料・以前に `render` した資料）からデータを起こすなら、`extract` で取り出してから直す。 ```bash uv run python scripts/pptx_builder.py extract filled.pptx --def def.yaml -o data.yaml ``` ### T6: この文書専用の単体スクリプトにする（任意） ```bash uv run python scripts/pptx_builder.py export --def def.yaml -o render_report.py uv run render_report.py --data data.yaml -o out.pptx # PEP 723 で依存（lxml・python-pptx・pyyaml）を自動で入れる ``` - テンプレートは既定では別ファイルのまま、スクリプトからの相対パスで読む。1 ファイルにしたいときだけ `--embed` - `--data` には、分けたデータの複数のファイルかフォルダも渡せる - `--example-data` でデータの雛形と収まる量、`--extract-def` で埋め込みの定義を取り出せる - 改修は、スクリプトを手で書き換えず、定義を直して `export --from-script render_report.py --def def.yaml -o render_report.py` で書き出し直す。`--def` を付けなければエンジンだけを最新にする ### T7: 確かめる 1. 出力を画像にして、スライドごとに見る（`soffice --headless --convert-to pdf out.pptx` → `pdftoppm -png -r 50 out.pdf page`）。文字のはみ出し・図形の重なり・矢印のつながりを確かめる 2. サンプルの値（`サンプル`・前の顧客名・前の日付）が残っていないか確かめる 3. 流用した場合は、文書のプロパティ・ノート・コメントに、元のプロジェクトの情報が残っていないか確かめる テストの実行: `uv run python -m unittest discover -s tests -v` 具体的な資料で依頼から出来上がりまでを通すシナリオは [tests/scenarios/](tests/scenarios/README.md) にある。エージェントに「このシナリオを再生して」と頼んで回す。 ## フローの詳細: 新規生成（#6） 1. 内容と構成を確認する。数値・事実は捏造しない 2. JSON スペックを組む。構造は [references/spec.md](references/spec.md)。雛形は `uv run python scripts/pptx_builder.py example` 3. 生成する: `uv run python scripts/pptx_builder.py build --spec spec.json` 4. 収まらない内容（箇条書きの行数・手順の段数・カードの枚数・表の行数）があれば、`render` と同じく挙げて止まる。量を調整して作り直す 5. T7 と同じく、画像にして確かめる スライドの種類は `title`・`bullets`・`table`・`flow`（手順。図形と矢印のコネクタ）・`cards`（並列の項目。角丸の図形の格子）。作った資料は、そのままテンプレートとして #1 に使える。 ## サブコマンド一覧（個別に呼ぶ場合） すべて `uv run python scripts/pptx_builder.py <サブコマンド>`。 | サブコマンド | 役割 | 主な引数 | |--------------|------|----------| | `inspect <template.pptx>` | テンプレートの事実（図形・文字・大きさ・収まる量・図の並び・仮値の疑い・来歴）を出す | `--json` | | `analyze <template.pptx>` | 定義の下書きを書く（確定ではない） | `-o def.yaml`（拡張子で JSON / YAML を選ぶ） | | `check --def <def>` | 定義の整合と、テンプレートの値の残り（`strict`）を検査し、収まる量の一覧を出す | `--template` | | `render --def <def> --data <data> -o <out.pptx>` | テンプレート + 定義 + データから再構成する | `--template`、`--data -`（標準入力）、`--data a.yaml b.yaml` / `--data DIR`（分けたデータをまとめる）、`--allow-overflow` | | `extract <filled.pptx> --def <def>` | 記入済みの資料から、定義に沿ってデータを取り出す（`render` の逆） | `-o data.yaml`（省略時は標準出力に JSON）、`--template`、`--split DIR`（スライドのまとまりごとのファイルに分ける） | | `export --def <def> -o <render.py>` | 定義を埋め込んだ、単体で動く専用スクリプトを書き出す | `--embed`、`--template`、`--from-script <旧.py>` | | `build --spec <spec.json>` | テンプレート無しで、JSON スペックから新規生成する | stdin も可、`--allow-overflow` | | `example` | `build` のサンプルスペックを出す | — | ## できること / できないこと | 対象 | 可否 | |------|------| | プレースホルダー・テキストボックス・図形の文字の差し替え（段落・文字の書式を保つ） | ✅ | | 同じ形のスライドの繰り返し・見本のスライドの削除 | ✅ | | 箇条書きの項目数・段（レベル）の増減 | ✅ | | 表の行の増減（見出し・合計の行は残す）、○× などの変換 | ✅ | | 図の並び（横・縦・格子）の増減。図形・矢印のコネクタを複製し、つながりを付け直す | ✅ | | 収まる量の検査（サンプルの粒度・図形に収まる行数・表の高さ）と、続きのスライドへの分割 | ✅ | | 文体の検査（文末・1 文の長さ・数字と句読点の表記）と、趣旨・論理構成の書き添え | ✅ 趣旨・論理構成は LLM が書き、データを書くときに使う | | グラフの値・SmartArt・画像の差し替え | ❌ そのまま残す（`inspect` が挙げる） | | 折れ線のつなぎ・格子の並びの矢印 | ❌ 横・縦の並びの、まっすぐな矢印だけ | ## ガードレール | 制限 | 内容 | |------|------| | データの事実性 | 依頼に無い数値・事実を作らない。量を減らすときは要約・統合し、意味を変えない | | スタイル | 文字の大きさ・図形の大きさ・色・間隔をデータに合わせて変えない。合わせるのはデータの量 | | 書きぶり | サンプルの文末・表記・スライドの趣旨を、データに合わせて変えない。合わない内容は、ユーザーに聞く | | 図 | 図は pptx の図形で作る。画像（PNG など）に描いて貼らない | | 機密 | 流用元の実データ・ノート・コメント・プロパティを持ち越さない |