pptx-from-layouts

PPTX from Layouts — Step 3: Render

Markdown のアウトラインからテンプレートの実際のスライドマスターレイアウトに内容を入力し、コンサルタントがすぐに使える PowerPoint プレゼンテーションを生成します。中心となる考え方：テンプレートのレイアウトとプレースホルダーを使い、スライドにテキストボックスを重ねることは決してしません。

3 ステップのパイプライン

このスキルは、3 つのスキルで構成されるパイプラインの Step 3 です。各ステップはそれぞれ独立したスキルです。

  STEP 1 — PROFILE          STEP 2 — AUTHOR           STEP 3 — RENDER  ◀ you are here
  pptx-profile              pptx-author               pptx-from-layouts
  ───────────────           ───────────────           ─────────────────
  your-template.pptx        slides.md (+ [HINT:])     slides.md + config
        │                         │                         │
        ▼                         ▼                         ▼
   catalog.py  ──catalog.md──▶  write & lint  ──slides──▶  generate.py ─▶ deck.pptx
        └────────────────── config.json ───────────────────▲   (validated)
  "what layouts do I        "write slides that        "fill the template's
   have?"                    name real layouts"        actual placeholders"

• Step 1 — pptx-profile: catalog.py で .pptx をレイアウトカタログ（[HINT:] 名の一覧）とレンダリング用 config.json に変換します。テンプレートごとに 1 回実行します。
• Step 2 — pptx-author: 各スライドに [HINT: layout_name] を指定した slides.md を作成し、lint_hints.py でカタログに照らしてヒントを検証します。
• Step 3 — このスキル： generate.py で指定されたレイアウトに内容を入力し、検証します。

同梱の Inner Chapter テンプレートを使って、ここから直接始めることもできます（Step 1 は不要です）。このテンプレートはデフォルトで、このドキュメント全体を通じて実行例として使われています。

[HINT:] — 実際のレイアウトに合わせて作成する

スライドでは、レンダリングに使用するテンプレートレイアウトを正確に指定できます。

# Slide 2: Three outcomes the research must achieve

[HINT: column-3-centered-a]

[Column 1: Level-set] …

[HINT:] は、アクティブなテンプレート設定（Step 1 で作成）を参照するため、Inner Chapter 以外のプロファイル済みテンプレートでも機能します。**Layout:** マーカーと同等で、**Visual:** より優先されます。レイアウトが分かっている場合（正確に指定する場合）は [HINT:] を使い、意味上の意図（例：process-4-phase）に合わせてエンジンに自動選択させたい場合は **Visual:** を使います。ヒントが一致しない場合は警告を出して自動検出に切り替わるため、先に Step 2 で lint を実行してください。

依存関係（最初に確認）

Python 3.10+、python-pptx、pydantic が必要です。

pip install python-pptx pydantic     # or: pip install -r requirements.txt

ModuleNotFoundError: No module named 'pptx' または 'pydantic' が表示された場合は、これが原因です。エントリーポイントのスクリプトは独自の PYTHONPATH を設定するため、python で直接実行してください。

判断：どの方法を使いますか？

ユーザーの要望…	実行すること
ブリーフ／メモ／ソース文書からプレゼンテーションを作りたい（アウトラインはまだない）	pptx-outline-architect に委任してから生成する
プレゼンテーションを作りたい。アウトラインはすでにある	generate.py → 検証
独自の PowerPoint をテンプレートとして使いたい	pptx-template-onboarder に委任する（初回のみの設定）
既存のプレゼンテーションで、テキストの軽微な修正／順序変更をしたい（スライドの 30% 未満）	edit.py（一覧作成 → 置換／並べ替え）
レイアウト変更、スライドの追加／削除、または 30% を超える変更がある	generate.py で再生成する — 編集は決してしない
プレゼンテーションの品質を確認したい	pptx-deck-qa に委任するか、validate.py を実行する

必須の生成ワークフロー（手順を省略しないでください）

1. テンプレートを選ぶか、確認します。 カスタムテンプレートを初めて使う場合は、一度オンボーディングしてください（下記の 独自のテンプレートを使う を参照）。それ以外の場合は、同梱の Inner Chapter テンプレートがデフォルトです。
2. アウトラインを作成します。 すべてのコンテンツスライドに **Visual: <type>** の宣言を付けてください。以下の判断順序に従ってビジュアルタイプを選び、すべてを箇条書きにすることは避けてください。
3. 生成します：

   python scripts/generate.py outline.md -o deck.pptx --validate
   

   （カスタムテンプレートの場合は --template <t.pptx> --config <c.json> を追加してください。）
4. 検証し、レポートを読みます。 エラーとテキストのはみ出しがなくなるまで、プレゼンテーションは完成ではありません。問題があれば修正して再実行してください。
5. スコアと出力先のパスをユーザーに報告します。

完了の定義（成功を伝える前のセルフチェック）

• すべてのコンテンツスライドに明示的な **Visual:** 宣言がある。
• generate.py が正常終了し、.pptx が存在する。
• validate.py でエラーがゼロ、かつテキストのはみ出しがないことが報告されている。
• 以下のアンチパターンを使っていない（リストにヒーローステートメント、プロセスフローに表、比較に箇条書きなど）。
• 「完了」とだけ伝えるのではなく、検証スコアとファイルパスを報告した。

未チェックの項目がある場合、タスクは完了していません。修正するか、何が妨げになったのかを明確に伝えてください。

サブエージェント

標準定義は agents/ にあります。使用するには ~/.claude/agents/ にインストールしてください。

サブエージェント	用途
pptx-outline-architect	生の素材を、適切なビジュアルタイプを指定した生成準備済みの outline.md に変換します
pptx-template-onboarder	ユーザーの .pptx を再利用可能な、ブランドに沿ったテンプレートとしてオンボーディングします（初回のみ）
pptx-deck-qa	デッキを検証し、必要最小限の修正を適用するか、再生成を推奨します

連携の流れは architect → generate.py → QA です。独自のテンプレートを使う場合は、 最初に onboarder を一度実行します。（詳しい説明はリポジトリの docs/workflows.md を参照してください。）

クイックスタート

# Generate from outline (bundled Inner Chapter template, with validation)
python scripts/generate.py outline.md -o deck.pptx --validate

# Use your own template
python scripts/generate.py outline.md -o deck.pptx \
    --template your-template.pptx --config your-template-config.json --validate

# Edit existing deck (dump inventory, edit its JSON, apply as a file)
python scripts/edit.py deck.pptx --inventory -o inv.json
#   edit inv.json: change the text on the paragraph(s) you care about
python scripts/edit.py deck.pptx --replace inv.json -o edited.pptx

# Validate quality
python scripts/validate.py deck.pptx

# Profile a custom template (one-time onboarding)
python scripts/profile.py template.pptx --name my-template --generate-config

独自のテンプレートを使用する（初回のみ、その後は自動化）

同梱のテンプレートはデモ用です。ブランドに沿ったデッキを作成するには、独自の .pptx を一度だけオンボーディングします。プロファイルを作成し、レイアウトマッピング設定を生成して、スモークテストを実行すれば、以降のすべてのデッキで再利用できます。

python scripts/profile.py /path/to/your-template.pptx \
    --name your-template --generate-config --output-dir templates/

これにより your-template-config.json が出力されます。その後は、各デッキを --template／--config を指定した generate.py の呼び出し一回で作成できます。詳しいガイド： rules/bring-your-own-template.md。全体を自動化するには、 pptx-template-onboarder に委任してください。

ビジュアルタイプ

アウトラインでは **Visual: type-name** として指定します。

タイプ	用途
process-N-phase	順序のあるステップ（N=2-5）
comparison-N	並列で比較する選択肢（N=2-5）
cards-N	順序のない並列項目（N=2-5）
data-contrast	対照的な2つの指標
quote-hero	印象的な引用
hero-statement	ひと目を引く単独のメッセージのみ
timeline-horizontal	日付順の流れ
table	表形式が適切なデータ
bullets	デフォルト（3項目以上）— 最終手段

選択の優先順： 順序 → 比較 → 並列項目 → データの対比 → 引用 → 表 → ヒーロー → 箇条書き。全タイプの説明とタイプ別の長さ制限： rules/visual-types.md。

タイポグラフィマーカー

インライン	結果		段落	結果
{blue}text{/blue}	IC ブランドブルー		{bullet:-}	ダッシュ付き箇条書き（–）
{bold}text{/bold}	太字		{bullet:1}	番号付き
{italic}text{/italic}	斜体		{level:N}	インデントレベル
{question}text?{/question}	青色の斜体
{signpost}LABEL{/signpost}	セクションラベル

アウトラインの例

# Project Overview
**Visual: hero-statement**
Transforming operations through digital innovation

# Our Approach
**Visual: process-4-phase**

[Column 1: Discover]
- Stakeholder interviews
- Competitive audit
[Image: research process]

[Column 2: Define]
- Workshop facilitation
- Strategic framework

[Column 3: Design]
- Solution architecture
- Prototype development

[Column 4: Deliver]
- Implementation
- Training & handover

編集ワークフロー

# 1. Dump the inventory — this is the schema replace.py consumes
python scripts/edit.py project.pptx --inventory -o inv.json
# 2. Open inv.json, find the target paragraph, change only its "text" field.
#    e.g. inv.json["slide-2"]["shape-3"]["paragraphs"][0]["text"] = "Q2 2026"
# 3. Apply, then validate
python scripts/edit.py project.pptx --replace inv.json -o updated.pptx
python scripts/validate.py updated.pptx

モードの選択

変更の種類	アクション
新しいプレゼンテーション	generate.py
誤字・値の修正（スライドの 30% 未満）	edit.py
スライドの並べ替え	edit.py --reorder
レイアウトの変更	再生成
スライドの追加・削除	再生成
スライドの変更が 30% 超	再生成

アンチパターン（禁止）

• **Visual:** の指定を省略しないでください。パーサーのデフォルトが適切とは限りません。
• より適したビジュアルタイプがある場合に、安易に箇条書きを使わないでください。箇条書きは 最終手段であり、反射的に選ぶものではありません。
• 3項目以上や複数文の内容に hero-statement を使わないでください。
• 手法やプロセスの流れに表を使わないでください（process-N-phase を使用してください）。
• 並列の比較に箇条書きを使わないでください（comparison-N を使用してください）。
• レイアウトの変更やスライドの追加・削除に編集モードを使わないでください。再生成してください。
• スライドの 30% を超えて編集しないでください。代わりに再生成してください。
• 検証に問題がないことを確認せずに、成功したと報告しないでください。

関連項目

作成者向けルールは rules/ にあります： outline-format.md、visual-types.md、typography.md、columns.md、 tables.md、editing.md、bring-your-own-template.md、decisions.md。

リファレンス：references/layouts.md（Inner Chapter のレイアウトインデックス）。 サブエージェント：agents/（このスキル）。ワークフローの説明：docs/workflows.md（リポジトリ）。