pptx-generator

PPTX スライドジェネレーター

python-pptx を使用して、プロフェッショナルでブランドイメージに沿ったプレゼンテーションスライドを生成します。このスキルでは、以下をサポートします。

• スライド生成 - brands/ 内の任意のブランド向けにプレゼンテーションを作成
• カルーセル生成 - LinkedIn カルーセルを作成（正方形フォーマット、PDF にエクスポート）
• スライド編集 - 既存の PPTX ファイルを編集
• レイアウト管理 - クックブックレイアウトを作成、編集、更新

重要： スキルのリソースはすべて .claude/skills/pptx-generator/ にあります。ファイルを探す際は、必ず .claude/skills/pptx-generator/ で始まる Glob パターンを使用してください。

---

⚠️ 重要：バッチ生成のルール

一度に5枚を超えるスライドを生成しないでください。

ルール	詳細
バッチあたりの最大スライド数	5（1、2、3、4、5枚のいずれでも可）
各バッチの後	停止して出力を検証する
必須の検証	次を確認：タイトルの重複がないこと、適切な余白、正しい色
続行するタイミング	検証に合格した場合
すべてのバッチの後	単一のファイルに結合し、パートファイルを削除する

これにより、トークン制限によるエラーを防ぎ、早い段階で品質の問題を検出できます。

重要：結合後は必ずパートファイルを削除してください。 ユーザーに表示する PPTX ファイルは最終版の1つだけにしてください。複数のパートファイルを残さないでください。

---

⚠️ 前提条件：ブランドの確認

スライドを生成する前に、ブランドが存在するか確認してください。

Glob: .claude/skills/pptx-generator/brands/*/brand.json

ブランドが見つからない場合（template/ のみが存在する場合）：

1. 停止 - スライド生成を続行しない

2. ユーザーに確認する：

   「まだブランドが設定されていません。まずブランドの作成をお手伝いしましょうか？ 設定には、ブランドカラー、フォント、スタイルガイドラインが必要です。」

3. ユーザーがブランドの作成を希望する場合は、 以下の 新しいブランドの作成 セクションに従ってください。

4. ユーザーが希望しない場合は、 スライドにはブランド設定が必要であることを説明し、代替案として汎用スタイルの使用を提案してください。

---

新しいブランドの作成

ブランドが存在しない場合、またはユーザーが新しいブランドを希望する場合：

ステップ 1：テンプレートを読む

Read: .claude/skills/pptx-generator/brands/template/README.md
Read: .claude/skills/pptx-generator/brands/template/brand.json
Read: .claude/skills/pptx-generator/brands/template/config.json

ステップ 2：ブランド情報を収集する

ユーザーに次の情報を尋ねます（または提供された資料から抽出します）。

必須	説明
ブランド名	フォルダー名（小文字、スペースなし）
カラー	背景色、テキスト色、アクセントカラー（16進数コード）
フォント	見出し用フォント、本文用フォント、コード用フォント

任意	説明
出力ディレクトリ	生成したファイルの保存先（デフォルト：output/{brand}）
ロゴ	ロゴファイルのパス（PNG/SVG）
ブランドガイドライン	参考にする既存のスタイルガイドまたはウェブサイト
口調	文章のスタイル、好みの語彙

ステップ 3：ブランドファイルを作成する

1. ブランドフォルダーを作成する：

   mkdir -p .claude/skills/pptx-generator/brands/{brand-name}
   

2. 収集した値を使って brand.json を作成する：

   {
     "name": "Brand Name",
     "description": "One-line description",
     "colors": {
       "background": "hex-without-hash",
       "background_alt": "hex-without-hash",
       "text": "hex-without-hash",
       "text_secondary": "hex-without-hash",
       "accent": "hex-without-hash",
       "accent_secondary": "hex-without-hash",
       "accent_tertiary": "hex-without-hash",
       "code_bg": "hex-without-hash",
       "card_bg": "hex-without-hash",
       "card_bg_alt": "hex-without-hash"
     },
     "fonts": {
       "heading": "Font Name",
       "body": "Font Name",
       "code": "Monospace Font"
     },
     "assets": {
       "logo": "assets/logo.png",
       "logo_dark": null,
       "icon": null
     }
   }
   

3. 出力設定を使って config.json を作成する：

   {
     "output": {
       "directory": "output/{brand}",
       "naming": "{name}-{date}",
       "keep_parts": false
     },
     "generation": {
       "slides_per_batch": 5,
       "auto_combine": true,
       "open_after_generate": false
     },
     "defaults": {
       "slide_width_inches": 13.333,
       "slide_height_inches": 7.5
     }
   }
   

4. brand-system.md を作成する - テンプレートをコピーし、ブランドガイドラインを記入する

5. tone-of-voice.md を作成する - テンプレートをコピーし、口調のガイドラインを記入する

6. アセットを追加する - ロゴや画像を brands/{brand-name}/assets/ にコピーする

ステップ 4：確認する

ブランドを作成した後、次を実行して確認します。

Glob: .claude/skills/pptx-generator/brands/{brand-name}/*

その後、スライド生成に進みます。

---

スキルのモード

このスキルは3つのモードで動作します。

モード 1：プレゼンテーションスライドを生成する

ユーザーが、ブランドのスタイルを使用したプレゼンテーションスライド（16:9）の作成を希望しています。 → 次の手順に従います：ブランドの確認 → レイアウトの選択 → コンテンツの調整 → 実行 → レイアウトの場所：cookbook/*.py

モード 2：LinkedIn カルーセルを生成する

ユーザーがソーシャルメディア向けの LinkedIn カルーセル（正方形の1:1フォーマット）を希望しています。 → 次の手順に従います：ブランドの確認 → カルーセルの計画 → 生成 → PDF へのエクスポート → レイアウトの場所：cookbook/carousels/*.py

モード 3：クックブックレイアウトを管理する

ユーザーがレイアウトテンプレートの作成、編集、改善を希望しています。 → 「レイアウトの CRUD 操作」セクションに従います。

---

モード 1：プレゼンテーションスライドを生成する

ステップ 1：ブランドの確認

1. 利用可能なブランドを一覧表示します：

   Glob: .claude/skills/pptx-generator/brands/*/brand.json
   

   パスからブランド名を抽出し、重複を除去します（例：brands/rasmus/... → 「rasmus」）。

2. ブランド設定ファイルを読み込みます：

   Read: .claude/skills/pptx-generator/brands/{brand-name}/brand.json
   Read: .claude/skills/pptx-generator/brands/{brand-name}/config.json
   

   • brand.json - 色、フォント、アセット
   • config.json - 出力ディレクトリ、生成設定

3. 背景情報を得るために、関連する Markdown ファイルを読み込みます：

   Glob: .claude/skills/pptx-generator/brands/{brand-name}/*.md
   

   これらのファイルには、表現方法、トーン、デザイン思想が記載されています。

4. ブランドファイルから情報を抽出します：

   • brand.json から： 色（# を除いた 16 進数）、フォント、アセットのパス
   • config.json から： 出力ディレクトリ、バッチあたりのスライド数、命名規則
   • Markdown から： 表現方法、トーン、語彙、ビジュアルの原則

ブランドが見つからない場合は、利用可能なブランドを一覧表示して、ユーザーに選択を促します。

ステップ 2：レイアウトの確認（すべてのフロントマターを読む）

⚠️ 必須：レイアウトを選択する前に、すべてのレイアウトのフロントマターを読み込んでください。

十分な情報に基づいてレイアウトを選ぶために、このステップは重要です。選択する前に、すべてのレイアウトで何ができるかを把握する必要があります。

ステップ 2a：すべてのレイアウトを確認します：

Glob: .claude/skills/pptx-generator/cookbook/*.py

ステップ 2b：各レイアウトファイルをすべて読み込みます（1、2 個だけではありません）。

見つかった各 .py ファイルについて、最初の 40 行を読み込み、# /// layout フロントマターのブロックを抽出します。以下の項目を把握します。

• 各レイアウトの用途（purpose、best_for）
• 各レイアウトを使用すべきでない状況（avoid_when）
• 上限と制約（max_*、min_*、*_max_chars）

フロントマターのブロックは次のような形式です。

# /// layout
# name = "floating-cards-slide"
# purpose = "Feature highlights, process steps, multiple equal items with depth"
# best_for = [
#     "Exactly 3 related features or concepts",
#     "Process with 3 steps",
# ]
# avoid_when = [
#     "More than 3 items - use multi-card-slide instead",
#     "Long card titles (over 15 characters)",
# ]
# max_cards = 3
# card_title_max_chars = 15
# instructions = [
#     "EXACTLY 3 cards required - no more, no less",
#     "Card titles must be SHORT: 1-2 words, max 15 characters",
# ]
# ///

主なフロントマターフィールド：

フィールド	説明
name	レイアウト識別子
purpose	このレイアウトの用途
best_for	最適な使用例（配列）
avoid_when	このレイアウトを使用すべきでない状況（配列）
max_* / min_*	項目の上限（カード、箇条書き、統計情報）
instructions	このレイアウトを使用するための具体的なヒント

ステップ 2c：レイアウトを選択します（すべてのフロントマターを読んだ後に限ります）。

利用可能なレイアウトとその制約を把握したら、次の手順で選択します。

1. ユーザーがレイアウトを指定した場合 → そのレイアウトを使用します（ただし、コンテンツに適しているか確認します）。
2. ユーザーがコンテンツを説明した場合 → 最も適合する best_for の基準に照らし合わせます。
3. avoid_when を確認します → 使用しないよう警告されている状況では、そのレイアウトを使用しません。
4. 上限を守ります → コンテンツが max_* を超える場合は、別のレイアウトを使用します。
5. 複数のスライドが必要な場合 → 各スライドに適したレイアウトを選択します。
6. 適切なレイアウトがない場合 → カスタムレイアウトを作成します（モード 2 を参照）。

選択プロセスの例：

• ユーザーが「AI インフラの 5 つの柱」を希望している
• すべてのフロントマターを読み、次のことを把握している：
  • floating-cards-slide：max_cards = 3 → 使用できない
  • multi-card-slide：max_cards = 5 → ぴったり
• multi-card-slide を選択する

すべてのフロントマターを読む理由

• レイアウトは avoid_when で相互に参照することがあります（例：「代わりに multi-card-slide を使用」）。
• すべての選択肢を把握していなければ、適切な選択はできません。
• レイアウトが適合しなかった場合に、後戻りして選び直すことを防げます。

ステップ 2d：ビジュアル優先のレイアウト選択（バリエーションのために重要）

🎨 ビジュアルレイアウトを標準とします。content-slide は最終手段であり、標準ではありません。

バリエーションの問題

プレゼンテーション作成で最もよくある間違いは、伝える情報があるたびにcontent-slide（タイトル＋箇条書き）を標準として選ぶことです。こうすると、プレゼンテーションが単調で退屈になります。

よくある失敗パターン：

• 30 枚中 11 枚のスライドが content-slide（37% の繰り返し）
• ユーザーが「バリエーションが足りない」と言う
• 「でも、11 種類の異なるレイアウトを使った」と考える
• 実際にはレイアウトの種類は豊富でも、配分に大きな偏りがあります

バリエーションを保つためのルール

厳格な上限：

1. 同じレイアウトを 2〜3 枚を超えて連続で使用しないでください。
2. content-slide はスライド全体の 25% 未満にしてください（35〜40% ではありません）。
3. ビジュアルレイアウト（カード、統計情報、列、ヒーロー、斜め配置）はスライドの 50% 以上にしてください。
4. セクション区切りはバリエーションではありません。構造上の要素なので、バリエーションには数えません。

判断フロー：「content-slide を使うべきですか？」

content-slide を標準として選ぶ前に、次の質問を上から順に確認してください。

Do I have 3-5 equal items?
  YES → Use multi-card-slide (not content-slide)

Do I have 2-4 big numbers/metrics?
  YES → Use stats-slide (not content-slide)

Am I comparing two things?
  YES → Use two-column-slide (not content-slide)

Do I have a central concept with surrounding items?
  YES → Use circular-hero-slide (not content-slide)

Do I have exactly 3 related items?
  YES → Use floating-cards-slide (not content-slide)

Do I have 1-3 words I want to emphasize dramatically?
  YES → Use giant-focus-slide or bold-diagonal-slide (not content-slide)

Do I have a powerful quote or principle?
  YES → Use quote-slide (not content-slide)

Is this the ONLY way to present this information?
  YES → NOW you can use content-slide
  NO → Go back through the decision tree

箇条書きをビジュアルレイアウトに変換する

例 1：「検証パターン」

❌ 悪い例（content-slide）：

Title: Validation Patterns
Bullets:
- Run comprehensive test suites
- Type checking and linting
- Code review by humans and AI
- Deployment previews

✅ 良い例（multi-card-slide）：

Title: Validation Patterns
Cards:
1. Testing | Run comprehensive test suites after every change
2. Linting | Type checking and formatting as guardrails
3. Review | Human and AI code review process
4. Preview | Deployment previews for visual regression

例 2：「PIV が機能する理由」

❌ 悪い例（content-slide）：

Title: Why PIV Works
Bullets:
- Forces planning before implementation
- Validation catches issues immediately
- Iterative improvements compound
- System gets smarter with every bug

✅ 良い例（3 枚のカードを使った floating-cards-slide）：

Title: Why PIV Works
Cards:
1. Plan First | Forces architectural thinking before coding
2. Fast Feedback | Validation catches issues immediately
3. Compounds | System improves with every bug

（注：floating-cards-slide の max_cards 上限に合わせるため、項目を 4 つから 3 つに減らしています）

例 3：「Human-in-the-Loop 戦略」

❌ 悪い例（content-slide）：

Title: Human-in-the-Loop Strategy
Bullets:
- In-the-loop: Human approves before execution
- On-the-loop: Human reviews after completion
- Code review remains critical
- AI generates, humans validate

✅ 良い例（two-column-slide）：

Title: Human-in-the-Loop Strategy
Left: In-the-Loop
- Human approves before execution
- Critical for production changes
- Quality gateway

Right: On-the-Loop
- Human reviews after completion
- Faster iteration cycles
- AI generates, human validates

ビジュアルを積極的に検討する

スライドを計画する前に、次のことを自問してください。

1. 「もっとビジュアルにできないか？」 — 答えはほとんどの場合「できます」です
2. 「直近 2 枚のスライドで content-slide を使ったか？」 — 使った場合は、別のものを使ってください
3. 「このスライドは前のスライドと似ていないか？」 — 似ている場合は、レイアウトを変えてください
4. 「パターンに陥っていないか？」 — すぐに打破してください
5. 「カード／列／統計情報にすると、もっと魅力的にならないか？」 — たいていは、なります

content-slide が適切な場合

content-slide は、次の場合に限って使用してください。

• 他のすべてのレイアウトを実際に試してみたものの、合わない
• 情報が本質的に直線的かつテキスト中心である（まれなケース）
• 2 つの複雑なビジュアルの間に「息抜き」のスライドが必要である
• レイアウトの配分上限に達している（最近、ビジュアル系のレイアウトをすべて使っている）

content-slide をデフォルトの選択肢にしないでください。

クイックリファレンス：コンテンツの種類 → 最適なレイアウト

コンテンツの種類	最適なレイアウト	理由
3～5 個の同等な機能／手順	multi-card-slide	カードによってビジュアルの階層構造を作れます
ちょうど 3 つの注目項目	floating-cards-slide	浮かせたカードで奥行きが生まれます
2～4 個の指標／KPI	stats-slide	大きな数字が注目を集めます
ビフォー／アフターの比較	two-column-slide	横並びにすることで違いがわかりやすくなります
種類を持つハブの概念	circular-hero-slide	放射状のパターンで関係性を表現できます
強い印象を与える強調（1～3 語）	giant-focus-slide	大きさによってインパクトが生まれます
緊急性の高い警告	bold-diagonal-slide	動きのある図形で緊急性を伝えられます
印象的な引用／原則	quote-slide	出典を示すことで説得力が高まります
関連項目のリスト	multi-card-slide	箇条書きより効果的です
手順のあるプロセス	floating-cards-slide	テキストよりビジュアルの流れが効果的です
技術的な比較	two-column-slide	構造化して比較できます

content-slide を使用するのは、次の場合に限ってください。

• 上記のいずれにも当てはまらない
• 情報が真に直線的である
• ビジュアルのスライドの間に、テキスト中心の息抜きが必要である
• すでに多様性の上限に達している

ステップ 3：スライドの計画（必ず実施）

スライドを生成する前に、必ず文章で計画を作成してください。

これは、単一のスライド、複数スライドのバッチ、プレゼンテーション全体に適用されます。計画を立てることで、次のことを防げます。

• スライド間で内容が重複する
• レイアウトの選択を誤る
• 重要な情報が抜け落ちる
• 流れや構成が悪くなる

スライド計画表を作成してください。

| # | Layout | Title | Key Content | Notes |
|---|--------|-------|-------------|-------|
| 1 | title-slide | [Title] | [Subtitle, author] | Opening slide |
| 2 | content-slide | [Title] | [3-4 bullet points] | Main concepts |
| 3 | stats-slide | [Title] | [2-3 metrics] | Impact data |
| ... | ... | ... | ... | ... |

各スライドについて、次の項目を指定してください。

• スライド番号 - プレゼンテーション内の位置
• レイアウト - 使用するクックブックのレイアウト
• タイトル - 正確なタイトル文（重複がないか確認してください！）
• 主要コンテンツ - 箇条書き、統計、引用など
• メモ - 特別な考慮事項

計画チェックリスト：

• スライド間でタイトルが重複していない
• スライドから次のスライドへの流れが論理的である
• 各コンテンツタイプに適切なレイアウトが選ばれている
• コンテンツが選んだレイアウトに収まる
• バッチが論理的にまとまっている（各バッチ最大 5 枚）
• バリエーション確認：コンテンツスライドが全スライドの 25% 未満である
• バリエーション確認：同じレイアウトのスライドが 2～3 枚を超えて連続していない
• バリエーション確認：ビジュアルレイアウト（カード、統計、カラム、ヒーロー）がスライドの 50% 以上を占めている
• バリエーション確認：各コンテンツスライドについて、まず判断ツリーに照らして評価している

計画の作成後、生成を始める前に計画を簡潔に提示してください。

30 枚のプレゼンテーションにおける、バリエーションに富んだ構成の例：

• コンテンツスライド：6～7 枚（20～23%）
• セクション区切り：5 枚（17%）
• ビジュアルレイアウト：15～16 枚（50～53%）
  • 複数カード：3～4 枚
  • 2 カラム：2～3 枚
  • 統計：1～2 枚
  • フローティングカード：2～3 枚
  • サーキュラーヒーロー：1～2 枚
  • ジャイアントフォーカス／ボールドダイアゴナル：2～3 枚
  • 引用：1 枚
• タイトル／クロージング：2～3 枚（7～10%）

ステップ 4：コンテンツの調整

計画に含まれる各スライドについて、次の作業を行ってください。

プレゼンテーションのテキスト書式ルール

重要：すべてのスライドテキストに、以下のルールを適用してください。

要素	ルール	例
タイトル	末尾にピリオドやコンマを付けない	「AI が重要な理由」。「AI が重要な理由。」ではない
サブタイトル	末尾に句読点を付けない	「コーディングの未来」。「コーディングの未来。」ではない
箇条書き	完全文でない限り、末尾にピリオドを付けない	「開発の高速化」。「開発の高速化。」ではない
見出し	句読点を最小限にし、省略記号を使わない	「次に来るもの」。「次に来るもの……」ではない
統計／数値	すっきりした形式にし、末尾に句読点を付けない	「50%」。「50%。」ではない
CTA	末尾に句読点を付けない	「始めましょう」。「始めましょう。」ではない
ラベル	短くし、句読点を付けない	「ステップ 1」。「ステップ 1：」ではない

避けること：

• タイトル、箇条書き、ラベルの末尾にピリオドを付ける
• 見出しに省略記号（...）を使う
• 短いフレーズでコンマを多用する
• ラベル／ヘッダーの末尾にコロンを付ける
• 箇条書きでセミコロンを使う

例外： 完全文の説明や引用では、適切な句読点を使用できます。

ブランド価値のマッピング

1. brand.json の値をレイアウトのプレースホルダーに割り当てます。

   レイアウトのプレースホルダー	brand.json のパス
   BRAND_BG	colors.background
   BRAND_BG_ALT	colors.background_alt
   BRAND_TEXT	colors.text
   BRAND_TEXT_SECONDARY	colors.text_secondary
   BRAND_ACCENT	colors.accent
   BRAND_ACCENT_SECONDARY	colors.accent_secondary
   BRAND_ACCENT_TERTIARY	colors.accent_tertiary
   BRAND_CODE_BG	colors.code_bg
   BRAND_CARD_BG	colors.card_bg
   BRAND_CARD_BG_ALT	colors.card_bg_alt
   BRAND_HEADING_FONT	fonts.heading
   BRAND_BODY_FONT	fonts.body
   BRAND_CODE_FONT	fonts.code

   注： brand.json のカラー値はすべて、# を付けない 16 進数です。

2. ブランドのトーン（tone-of-voice.md を参照）に合わせてコンテンツを作成します。

3. レイアウトの構造（装飾要素、余白、階層）を維持します。

ステップ 5：バッチ生成（重要）

1 バッチあたり最大 5 枚です。これは厳守してください。

複数のスライドを生成する場合：

1. 1 つの PPTX ファイルに 1〜5 枚のスライドを生成します
2. さらに生成する前に、いったん停止して出力を確認します
3. 検証に合格した場合のみ、次のバッチに進みます
4. すべてのスライドが生成されるまで繰り返します

バッチ生成が重要な理由：

• トークン制限エラーを防ぎます
• バッチ間で品質を確認できます
• 問題が後続のバッチに波及する前に発見できます

⚠️ 背景に関する重要なバグ修正：

すべてのスライドで、背景を明示的に設定する必要があります。 slide.background.fill.solid() と slide.background.fill.fore_color.rgb を設定しないと、PowerPoint のデフォルトである白い背景になり、暗いテーマのブランドではテキストが読めなくなります。

すべてのスライドで必須：

slide = prs.slides.add_slide(prs.slide_layouts[6])
slide.background.fill.solid()  # ← REQUIRED
slide.background.fill.fore_color.rgb = hex_to_rgb(BRAND_BG)  # ← REQUIRED

特に以下の場合は重要です。

• 複数のバッチを生成する場合（各バッチで新しい Presentation オブジェクトが作成されます）
• ヘルパー関数を使ってスライドを作成する場合
• 別々の PPTX ファイルを結合する場合

実行方法：

推奨：ヒアドキュメントを使用します（ファイルは作成されません）：

uv run --with python-pptx==1.0.2 python << 'EOF'
# [Adapted code with brand values and content]
EOF

ヒアドキュメントが失敗する場合（Windows の問題）：一時ディレクトリを使用します：

# Create temp directory if needed
mkdir -p .claude/skills/pptx-generator/.tmp

# Write script to temp directory
# (create file at .claude/skills/pptx-generator/.tmp/gen.py)

# Execute
uv run --with python-pptx==1.0.2 python .claude/skills/pptx-generator/.tmp/gen.py

# MANDATORY: Clean up immediately after execution
rm .claude/skills/pptx-generator/.tmp/gen.py

重要：リポジトリのルートディレクトリに Python ファイルを作成しないでください。 必ずヒアドキュメントを使用するか、スキルフォルダー内の一時ディレクトリを使用してください。

ステップ 6：品質検証（必須）

各バッチの後、次に進む前に検証してください。

1. 生成された PPTX を開き、目視で確認します
2. 以下のよくある問題がないか確認します：

問題	確認する内容	修正方法
白い背景	ブランドカラーではなく、スライドの背景が白になっている	slide.background.fill.solid() を追加し、fore_color.rgb を設定する
タイトルの重複	同じタイトルのテキストがスライド内に 2 回表示されている	重複するテキストボックスを削除する
間隔の問題	タイトルがサブタイトルやコンテンツに近すぎる	下部要素の Y 位置を大きくする
テキストのはみ出し	コンテンツがスライドの範囲を超えている	フォントサイズを小さくするか、コンテンツを分割する
要素の欠落	装飾要素が表示されていない	図形の位置と色を確認する
色の誤り	ブランドと色が一致していない	16 進数の値を確認する（コード内に # を付けない）
句読点の誤り	タイトルや箇条書きの末尾にピリオドやカンマがある	不要な句読点を削除する

3. 問題が見つかった場合：

   • 次に進む前に、現在のバッチを修正します
   • 今後同じ問題が発生しないよう、問題を記録します

4. 検証に合格した場合：

   • 次のスライドのバッチに進みます

ステップ 7：出力

config.json の出力設定を使用します：

設定	デフォルト	説明
output.directory	output/{brand}	ファイルの保存先
output.naming	{name}-{date}	ファイル名のパターン
output.keep_parts	false	結合後もパートファイルを保持するかどうか

プレースホルダーを置き換えます：

• {brand} → ブランドフォルダー名
• {name} → ユーザーのリクエストにあるプレゼンテーション名
• {date} → 現在の日付（YYYY-MM-DD）

# Create output directory from config
mkdir -p {resolved-output-directory}

バッチ生成のワークフロー：

1. 各バッチを {name}-part1.pptx、{name}-part2.pptx などの名前で生成します
2. 次に進む前に、各バッチを検証します
3. すべてのバッチが完了したら、（auto_combine が true の場合）最終ファイルに結合します
4. （keep_parts が false の場合）パートファイルを削除します

ステップ 8：バッチを結合する（複数バッチのプレゼンテーションの場合）

🚨 重大なバグに関する警告：結合時に背景を設定する必要があります 🚨

プレゼンテーションを結合する際、add_slide() はデフォルトの白い背景でスライドを作成します。図形のコピーでは、スライドの背景プロパティはコピーされません。新しいスライドを作成したら、必ずすぐに背景を明示的に設定してください。

これは、結合したプレゼンテーションに白いスライドができる最も一般的な原因です。

すべてのバッチの検証が完了したら、1 つの PPTX に結合します。

uv run --with python-pptx==1.0.2 python << 'SCRIPT'
from pptx import Presentation
from pptx.dml.color import RGBColor
from pathlib import Path
import shutil

def hex_to_rgb(hex_color: str) -> RGBColor:
    h = hex_color.lstrip("#")
    return RGBColor(int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))

# Brand background color (get from brand.json)
BRAND_BG = "REPLACE_WITH_BRAND_BACKGROUND"  # e.g., "07090F"

# List all part files in order
output_dir = Path("output/{brand-name}")
part_files = sorted(output_dir.glob("{name}-part*.pptx"))

if len(part_files) > 1:
    # Start with first part as base
    combined = Presentation(part_files[0])

    # Add slides from remaining parts
    for part_file in part_files[1:]:
        part_prs = Presentation(part_file)
        for slide in part_prs.slides:
            # Copy slide layout and add to combined
            blank_layout = combined.slide_layouts[6]
            new_slide = combined.slides.add_slide(blank_layout)

            # 🚨 CRITICAL: Set background IMMEDIATELY after creating slide
            # PowerPoint defaults to WHITE background - this MUST be set before copying shapes
            new_slide.background.fill.solid()
            new_slide.background.fill.fore_color.rgb = hex_to_rgb(BRAND_BG)

            # Copy all shapes from source slide
            for shape in slide.shapes:
                # Clone shape to new slide
                el = shape.element
                new_slide.shapes._spTree.insert_element_before(
                    el, 'p:extLst'
                )

    # Save combined file
    combined.save(output_dir / "{name}-final.pptx")
    print(f"Combined {len(part_files)} parts into {name}-final.pptx")

    # MANDATORY: Clean up part files - user should only see final file
    for part_file in part_files:
        part_file.unlink()
        print(f"Deleted {part_file.name}")
else:
    # Single part, just rename
    shutil.move(part_files[0], output_dir / "{name}-final.pptx")
SCRIPT

最終出力： output/{brand-name}/{name}-final.pptx

このバグが発生する理由：

• combined.slides.add_slide() は、PowerPoint のデフォルトの白い背景を持つ新しいスライドオブジェクトを作成します
• shapes._spTree.insert_element_before() は図形（テキスト、長方形、画像）をコピーしますが、背景はコピーしません
• 背景は図形ではなくスライドのプロパティなので、別途設定する必要があります
• 背景を明示的に設定しないと、6～30 枚目のスライド（またはベースの後に追加された枚数分のスライド）が白くなります

結合後のテストチェックリスト：

• 結合した PPTX を開く
• 最初の数枚だけでなく、すべてのスライドを確認する
• すべてのスライドの背景色が正しいことを確認する
• 白いスライドが見つかった場合、結合コードで背景が設定されていません

---

モード 2：LinkedIn カルーセルを生成する

LinkedIn カルーセルは、正方形（1:1）形式の複数ページの PDF です。各ページはスワイプして表示するスライドです。

カルーセルとプレゼンテーションの比較

項目	プレゼンテーション	カルーセル
寸法	16:9（13.333" × 7.5"）	1:1（7.5" × 7.5"）
レイアウト	cookbook/*.py	cookbook/carousels/*.py
出力	PPTX	PDF（PPTX から変換）
スライド数	通常 10～50 枚以上	最適な枚数は 5～10 枚
テキストサイズ	標準	大きめ（モバイルで読みやすい）
コンテンツ	詳細	1 枚につき 1 つのアイデア

ステップ 1：ブランドを確認する

モード 1 と同様に、brand.json、config.json、tone-of-voice.md を読み込みます。

ステップ 2：カルーセルのレイアウトを確認する

カルーセル専用のレイアウトを確認します：

Glob: .claude/skills/pptx-generator/cookbook/carousels/*.py

利用可能なカルーセルレイアウト：

レイアウト	目的	最適な用途
hook-slide	注目を集めるオープニング	最初のスライドのみ
single-point-slide	説明付きの重要なポイント 1 つ	本文のコンテンツ
numbered-point-slide	大きな数字を使った番号付きリスト項目	リスト形式の投稿、手順
quote-slide	引用と出典	社会的証明、洞察
cta-slide	行動喚起	最後のスライドのみ

各レイアウトの制限事項と制約を把握するために、フロントマターを読みます。

ステップ 3：カルーセルを計画する

一般的なカルーセルの構成（5～10 枚）：

| # | Layout | Content |
|---|--------|---------|
| 1 | hook-slide | Attention-grabbing hook |
| 2-8 | single-point or numbered-point | Body content |
| 9/10 | cta-slide | Call to action |

カルーセルのコンテンツルール：

• 1 枚につき 1 つのアイデア — 複数のポイントを詰め込まないでください
• 大きな文字 — モバイルで読める必要があります
• 短いコピー — 見出しは最大 50 文字、本文は最大 150 文字
• 明確な流れ — どのスライドも単独で見ても内容が伝わるようにします
• 強いフック — 最初のスライドでスクロールを止めます
• 明確な CTA — 最後のスライドで、次に何をすべきか伝えます

ステップ 4：カルーセルを生成する

カルーセルの寸法（正方形 1:1）：

prs.slide_width = Inches(7.5)
prs.slide_height = Inches(7.5)

すべてのスライドを 1 つの PPTX ファイルとして生成します（カルーセルは通常 5～10 枚なので、バッチ処理が必要になることはほとんどありません）。

実行：

uv run --with python-pptx==1.0.2 python << 'SCRIPT'
# Carousel generation code with 7.5" x 7.5" dimensions
SCRIPT

ステップ 5：PDF にエクスポートする

LinkedIn のカルーセル投稿には PDF が必要です。PPTX を PDF に変換します。

オプション A：LibreOffice を使用する（推奨）

libreoffice --headless --convert-to pdf --outdir output/rasmus output/rasmus/carousel.pptx

オプション B：soffice を使用する

soffice --headless --convert-to pdf output/rasmus/carousel.pptx

注： LibreOffice をインストールしておく必要があります。macOS の場合：brew install --cask libreoffice

ステップ 6：出力する

両方のファイルを保存します。

• output/{brand}/{name}-carousel.pptx — 編集可能なソース
• output/{brand}/{name}-carousel.pdf — LinkedIn に対応したファイル

カルーセルのチェックリスト

• ブランド設定を読み込む
• cookbook/carousels/ のカルーセルレイアウトのフロントマターを読む
• カルーセルの構成を計画する（フック → 本文 → CTA）
• テキストを短く保つ（フロントマターで文字数制限を確認する）
• 7.5" × 7.5" の寸法を使用する
• PPTX を生成する
• 出力を検証する
• PDF にエクスポートする
• LinkedIn のプレビューで PDF を確認する

---

モード 3：レイアウトの CRUD 操作

新しいレイアウトの作成

ユーザーから新しいレイアウトタイプを依頼された場合：

1. 既存のレイアウトを調べてパターンを把握します：

   Glob: .claude/skills/pptx-generator/cookbook/*.py
   

   2～3 個のレイアウトを読み、次の点を把握します：

   • コード構造とインポート
   • ブランド変数の使い方
   • 装飾要素のパターン
   • 配置の慣例

2. 次の品質基準に沿ってデザインします：

   本番環境で使える品質が必須です：

   • プロフェッショナルで洗練された外観
   • 視覚的に魅力的（単調またはありきたりではない）
   • 個性のある装飾要素
   • 明確な視覚的階層
   • 適切な余白の使い方

   適切な要素を使用します：

   • チャート - データの可視化には円グラフ、ドーナツグラフ、棒グラフ、縦棒グラフ
   • 画像 - スクリーンショットや写真用のプレースホルダー図形
   • 図形 - 視覚的な面白さを加える円、長方形、平行四辺形
   • カード - 奥行きを出すための影付きフローティングカード
   • 幾何学模様 - 角や端に配置する大胆な図形

   次のものは避けます：

   • テキストだけの単調なレイアウト
   • スタイル付けのないありきたりな箇条書き
   • 目立たない小さな装飾要素
   • すべてを中央に配置した退屈な構成

3. 詳細なフロントマターを含むレイアウトファイルを作成します：

   ⚠️ 重要：フロントマターは、将来の AI エージェント向けのドキュメントです。

   すべてのレイアウトには、将来の AI エージェントに次の内容を伝える包括的なフロントマターが必須です：

   • このレイアウトをいつ使うべきか（また、いつ使うべきでないか）
   • 正しく使う方法
   • どのような制限や制約があるか
   • 特定の選択が重要な理由

   #!/usr/bin/env -S uv run
   # /// script
   # requires-python = ">=3.11"
   # dependencies = [
   #     "python-pptx==1.0.2",
   # ]
   # ///
   # /// layout
   # name = "layout-name"
   # purpose = "When to use this layout - be specific"
   # best_for = [
   #     "Ideal use case 1",
   #     "Ideal use case 2",
   # ]
   # avoid_when = [
   #     "Situation to avoid 1 - and what to use instead",
   #     "Situation to avoid 2 - and what to use instead",
   # ]
   # max_items = 5  # or other relevant limits
   # instructions = [
   #     "Specific tip 1",
   #     "Specific tip 2",
   # ]
   # ///
   """
   LAYOUT: [Name]
   PURPOSE: [When to use this layout - be specific]
   
   CUSTOMIZE:
   - [List customizable elements]
   """
   
   # ... implementation
   

   必須のフロントマターフィールド（詳細かつ具体的に記述）：

   フィールド	説明	例
   name	レイアウト識別子（ファイル名と一致）	"multi-card-slide"
   purpose	1 行で明確に説明	"複数の項目を横一列のカードで表示。カードは 3～5 枚"
   best_for	最適なシナリオを詳しく記述した配列	["関連する機能がちょうど 3 つある場合", "3 ステップのプロセス"]
   avoid_when	代替案を含む具体的な状況	["項目が 3 つを超える場合は、代わりに multi-card-slide を使用"]
   instructions	正しく使用するための実践的なヒント	["カードのタイトルは短くすること：1～2 語、最大 15 文字"]

   任意ですが、推奨されるフィールド：

   フィールド	説明	例
   max_* / min_*	項目数の厳格な上限・下限	max_cards = 3, min_surrounding_items = 4
   *_max_chars	テキストの文字数制限	card_title_max_chars = 15

   適切なフロントマターを書くには：

   ✅ 推奨： 具体的で実践的な内容にします

   # avoid_when = [
   #     "More than 3 items - use multi-card-slide instead",
   #     "Long card titles (over 15 characters) - abbreviate or use content-slide",
   # ]
   # instructions = [
   #     "EXACTLY 3 cards required - no more, no less",
   #     "Card titles must be SHORT: 1-2 words, max 15 characters",
   #     "If titles are too long, abbreviate or use different layout",
   # ]
   

   ❌ 避ける： 曖昧で役に立たない内容にします

   # avoid_when = ["Too many items", "Wrong content"]
   # instructions = ["Use correctly", "Follow the pattern"]
   

   フロントマターは同僚に教えるためのものと考えてください。質問せずにこのレイアウトを正しく使うために、同僚が知っておくべきことは何でしょうか？

4. cookbook に保存します：

   .claude/skills/pptx-generator/cookbook/{layout-name}-slide.py
   

5. 新しいレイアウトを使ったサンプルを生成してテストします

既存のレイアウトの編集

1. レイアウトを探します：

   Glob: .claude/skills/pptx-generator/cookbook/*{name}*.py
   

2. フロントマターを含め、現在の構造を読み取って理解します

3. 次の内容を維持しながら変更します：

   • スクリプトヘッダーの形式
   • ブランド変数の命名規則
   • Docstring の形式（LAYOUT、PURPOSE、CUSTOMIZE）

4. 変更によって次の内容が変わる場合は、フロントマターを更新します：

   • レイアウトの最適な用途（best_for）
   • 使用を避ける状況（avoid_when）
   • 項目数の制限（max_*、min_*）
   • 使用方法の説明（instructions）

5. 同じファイルに保存します

6. 変更したレイアウトをテストします

レイアウトの更新・改善

レイアウトの品質向上を求められた場合：

1. 現在の弱点を分析します：

   • 視覚的に魅力的ですか？
   • 装飾要素は十分ですか？
   • 視覚的な階層構造は適切ですか？
   • 空間を有効に活用していますか？

2. 改善を加えます：

   • 大胆な幾何学図形を追加します
   • 色使いを改善します
   • 奥行きを加えます（影、重なり）
   • タイポグラフィのサイズを調整します
   • より特徴的な装飾要素を加えます

3. 機能を維持します — 動作している機能を壊さないでください

4. フロントマターを確認し、改善します：

   • best_for と avoid_when は引き続き適切ですか？
   • instructions に新しい制約が反映されていますか？
   • 改善から得た教訓を追加します
   • 要素のサイズや数が変わった場合は、制限を更新します

レイアウトの削除

ファイルを削除するだけです：

rm .claude/skills/pptx-generator/cookbook/{layout-name}.py

---

既存の PPTX ファイルの編集

ユーザーから既存の PPTX が提供された場合：

1. ファイルを読み込みます：

   from pptx import Presentation
   prs = Presentation("path/to/existing.pptx")
   

2. 分析します： スライドの枚数、スタイル、コンテンツ構成

3. 変更を適用します： スライドの追加・削除、コンテンツの更新、スタイルの変更

4. 出力ディレクトリに保存します（依頼がない限り、元のファイルを上書きしないでください）

---

技術リファレンス

スライドの寸法（16:9）：

• 幅：13.333 インチ
• 高さ：7.5 インチ
• セーフマージン：0.5 インチ

常に使用するもの：

• 空白のレイアウト：prs.slide_layouts[6]
• python-pptx のバージョン：1.0.2

一般的なインポート：

from pptx import Presentation
from pptx.chart.data import CategoryChartData
from pptx.dml.color import RGBColor
from pptx.enum.chart import XL_CHART_TYPE, XL_LEGEND_POSITION
from pptx.enum.shapes import MSO_SHAPE
from pptx.enum.text import PP_ALIGN, MSO_ANCHOR
from pptx.util import Inches, Pt

使用可能なグラフの種類：

• XL_CHART_TYPE.PIE - 円グラフ
• XL_CHART_TYPE.DOUGHNUT - ドーナツグラフ
• XL_CHART_TYPE.BAR_CLUSTERED - 横棒グラフ
• XL_CHART_TYPE.COLUMN_CLUSTERED - 縦棒グラフ
• XL_CHART_TYPE.LINE - 折れ線グラフ

グラフの追加：

chart_data = CategoryChartData()
chart_data.categories = ["A", "B", "C"]
chart_data.add_series("Values", [10, 20, 30])

slide.shapes.add_chart(
    XL_CHART_TYPE.DOUGHNUT,
    Inches(x), Inches(y),
    Inches(width), Inches(height),
    chart_data
)

画像の追加：

slide.shapes.add_picture(
    "path/to/image.png",
    Inches(x), Inches(y),
    width=Inches(w)  # Height auto-calculated
)

---

すべてのレイアウトをプレビュー

使用可能なすべてのレイアウトを確認するには：

uv run .claude/skills/pptx-generator/generate-cookbook-preview.py

これにより、すべてのレイアウトを含む cookbook-preview.pptx が生成されます。

---

チェックリスト

スライドの生成：

• 色とフォントを確認するため、brand.json を読む
• 出力ディレクトリと設定を確認するため、config.json を読む
• 文体やトーンを確認するため、Markdown ファイルを読む
• すべてのクックブックレイアウトのフロントマターを読む（各 .py ファイルの最初の 40 行）：
  • .claude/skills/pptx-generator/cookbook/*.py をすべて検索する
  • すべてのファイルを読み、# /// layout ブロックを抽出する
  • すべての best_for、avoid_when、制限事項を把握する
• その後、全体を把握したうえでレイアウトを選択する：
  • コンテンツを best_for の基準に合わせる
  • avoid_when の警告を守る
  • max_* / min_* の制限を確認する
  • 選択したレイアウトの instructions に従う
• 生成前にスライド計画表を作成する：
  • すべてのスライドについて、レイアウト、タイトル、コンテンツを一覧にする
  • タイトルの重複を確認する
  • 論理的な流れを確認する
  • バッチに分ける（各バッチ最大 5 枚）
  • バリエーション確認：コンテンツスライドは全体の 25% 未満
  • バリエーション確認：同じレイアウトのスライドが 3 枚以上連続しない
  • バリエーション確認：ビジュアルレイアウトがプレゼンテーション全体の 50% 以上
  • バリエーション確認：各コンテンツスライドの評価に判断ツリーを使用した
• 続行する前に計画を簡潔に提示する
• ブランドカラーとフォントを適用する
• ブランドの文体でコンテンツを書く
• 1 バッチにつき最大 5 枚のスライドを生成する（または、設定の slides_per_batch）
• UV REPL で実行する
• 続行する前に出力を検証する：
  • タイトルの重複がない
  • 要素間に適切な間隔がある
  • コンテンツが範囲内に収まっている
  • 色がブランドに合っている
  • タイトルや箇条書きの末尾に句読点がない
• 設定で指定された出力ディレクトリにバッチを保存する
• 必要に応じて次のバッチを繰り返す
• すべてのバッチを最終 PPTX に結合する（auto_combine が true の場合）
• パートファイルを削除する（keep_parts が false の場合）

レイアウトの作成：

• 既存のレイアウトを調べ、パターンを把握する
• 実運用に耐える品質で設計する
• 特徴的な装飾要素を含める
• チャート、画像、図形を適切に使用する
• TOML 形式のフロントマターを追加する。内容は次のとおり：
  • name、purpose
  • best_for、avoid_when の配列
  • 使用のヒントを含む instructions 配列
  • 必要に応じて max_* / min_* の制限
• 適切な docstring を記述する（LAYOUT、PURPOSE、CUSTOMIZE）
• 新しいレイアウトをテストする