pptx-presentation-builder
PowerPoint の資料を作るスキル。xlsx-report-builder の pptx 版で、考え方とサブコマンドは同じ。基本の使い方は、依頼のフレーズから流れ(フロー)を選んで進めること。個々のサブコマンドを直接呼ぶ使い方は、オプション(サブコマンド一覧)。
- テンプレート(体裁の決まった .pptx、前の案件の資料)がある → スライドのスタイル・図形をそのまま使い、内容を流し込む
- テンプレートが無い → JSON スペックから新規に生成する(凝った体裁の資料を一から作るなら presenter スキル)
pptx ならではの約束が 3 つある。
- 図は pptx の図形で作る。テンプレートやサンプルの図(矩形・角丸・丸・矢印線・ブロック矢印)は、その図形を複製・移動して使い、画像にしない。新規生成でも、流れは図形とコネクタで描く
- サンプルと同じ粒度に収める。文字の大きさ・図形の大きさ・間隔は変えず、データの量の方を合わせる。サンプルの文字数・項目数(
max_chars・max_items)と、図形に収まる行数を超えると、renderはどの欄を何字・何項目減らせばよいかを挙げて止まる。量を調整する(要約する・まとめる)のは LLM の仕事 - サンプルと同じ書きぶりにする。スライドごとの趣旨(何を言うスライドか)と論理構成(タイトル・本文・図のつなぎ方)、資料全体の流れを定義に書き、データはそれに沿って書く。文末(です・ます/だ・である/体言止め)・1 文の長さ・数字と句読点の表記は
analyzeがサンプルから測り、違う文があるとrenderが挙げて止まる
パスはこの SKILL.md からの相対パス。コマンド実行前にこのディレクトリに cd すること。
起動手順
スキル開始時に必ず実行する:
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。
段の一覧
| 段 | 何をするか | 誰が | コマンド |
|---|---|---|---|
| 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: テンプレートの事実を読む
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)。
| 単位 | 書くもの | 定義 |
|---|---|---|
| スライド | 趣旨(そのスライドで言いたいこと)、論理構成(タイトルで論点を言い切る → 根拠を 3 つ、など) | intent・logic |
| 欄 | 文末、1 文の長さ(analyze が測る。タイトルが言い切りか名詞止めか、箇条書きが体言止めか) |
ending・sentence_chars |
| 資料全体 | スライドの流れ(背景 → 課題 → 施策 → 効果、など)、数字と句読点の表記(表記は analyze が測る) |
style.logic・style.digits・style.punctuation |
- 趣旨は、スライドの見た目(箇条書き・表・図)ではなく、読み手に何を分かってもらうスライドかで書く。タイトルが論点を言い切る形(メッセージ型)か、話題の名前だけ(トピック型)かも見る
analyzeが測った文末は、サンプルが仮の文や書き方の説明なら外す- 判断の一覧と一緒に、趣旨・論理構成もユーザーに見せる
前の文書の値・メタデータを持ち越さない
analyze の下書きは、はじめから次の形になっている。外すのは、ユーザーが望んだときだけ。
strict: true。文字を持つ図形が、texts・lists・keep・clear・表・図のどれにも入らないまま残ると、checkとrenderがスライドと図形の名前を挙げて止まる。挙がったものを、そのまま全部keepに貼らないproperties.scrub: true。作成者・最終更新者・会社名・タイトルなどを空にし、プレビュー画像・カスタムプロパティ・コメントを取り除き、ノートを空にする(残すノートはnotesにキーを書く)。与えたい値(title: "第3四半期 報告")は同じpropertiesに書く- グラフの値・埋め込みのオブジェクト・外部へのリンク・非表示のスライドは、
inspectが挙げるが、自動では消さない。ユーザーに見せて扱いを決める
決めたら、判断の一覧(図形 | 役割 | 理由)をユーザーに見せて確認してもらう。確認前に定義を確定しない。
T3: 定義を検査する
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)。繰り返すスライドは配列。数値・事実を捏造しない。
check の一覧に出る趣旨・論理構成・文体に沿って書く。新しい内容は、資料全体の流れ(style.logic)の順に、趣旨の合うスライドへ入れる。どのスライドの趣旨にも合わない内容は、別のスライドに押し込まずにユーザーに聞く。
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 は、取り出したデータをこのまとまりごとのファイルに分けて書く。
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 で取り出してから直す。
uv run python scripts/pptx_builder.py extract filled.pptx --def def.yaml -o data.yaml
T6: この文書専用の単体スクリプトにする(任意)
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: 確かめる
- 出力を画像にして、スライドごとに見る(
soffice --headless --convert-to pdf out.pptx→pdftoppm -png -r 50 out.pdf page)。文字のはみ出し・図形の重なり・矢印のつながりを確かめる - サンプルの値(
サンプル・前の顧客名・前の日付)が残っていないか確かめる - 流用した場合は、文書のプロパティ・ノート・コメントに、元のプロジェクトの情報が残っていないか確かめる
テストの実行: uv run python -m unittest discover -s tests -v
具体的な資料で依頼から出来上がりまでを通すシナリオは tests/scenarios/ にある。エージェントに「このシナリオを再生して」と頼んで回す。
フローの詳細: 新規生成(#6)
- 内容と構成を確認する。数値・事実は捏造しない
- JSON スペックを組む。構造は references/spec.md。雛形は
uv run python scripts/pptx_builder.py example - 生成する:
uv run python scripts/pptx_builder.py build --spec spec.json - 収まらない内容(箇条書きの行数・手順の段数・カードの枚数・表の行数)があれば、
renderと同じく挙げて止まる。量を調整して作り直す - 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 など)に描いて貼らない |
| 機密 | 流用元の実データ・ノート・コメント・プロパティを持ち越さない |