Agent Skills: PowerPoint Automation

PowerPoint Automation

AI-powered PPTX generation using Orchestrator-Workers pattern.

When to Use

• PowerPoint, PPTX, create presentation, slides
• Convert web articles/blog posts to presentations
• Translate English PPTX to Japanese
• Create presentations using custom templates

Quick Start

From Web Article:

Create a 15-slide presentation from: https://zenn.dev/example/article

From Existing PPTX:

Translate this presentation to Japanese: input/presentation.pptx

Workflow

TRIAGE → PLAN → PREPARE_TEMPLATE → EXTRACT → TRANSLATE → BUILD → REVIEW → DONE

| Phase | Script/Agent | Description | | ------- | ------------------------- | ---------------------- | | EXTRACT | extract_images.py | Content → content.json | | BUILD | create_from_template.py | Generate PPTX | | REVIEW | PPTX Reviewer | Quality check |

Key Scripts

→ references/SCRIPTS.md for complete reference

| Script | Purpose | | ------------------------- | -------------------------------------- | | create_from_template.py | Generate PPTX from content.json (main) | | reconstruct_analyzer.py | Convert PPTX → content.json | | extract_images.py | Extract images from PPTX/web | | validate_content.py | Validate content.json schema | | validate_pptx.py | Detect text overflow |

content.json (IR)

All agents communicate via this intermediate format:

{
  "slides": [
    { "type": "title", "title": "Title", "subtitle": "Sub" },
    { "type": "content", "title": "Topic", "items": ["Point 1"] }
  ]
}

→ references/schemas/content.schema.json

Templates

| Template | Purpose | Layouts | | ---------------------- | --------------------------- | --------- | | assets/template.pptx | デフォルト (Japanese, 16:9) | 4 layouts |

template レイアウト詳細

| Index | Name | Category | 用途 | | ----- | ----------------------- | -------- | ---------------------- | | 0 | タイトル スライド | title | プレゼン冒頭 | | 1 | タイトルとコンテンツ | content | 標準コンテンツ | | 2 | 1_タイトルとコンテンツ | content | 標準コンテンツ（別版） | | 3 | セクション見出し | section | セクション区切り |

使用例:

python scripts/create_from_template.py assets/template.pptx content.json output.pptx --config assets/template_layouts.json

テンプレート管理のベストプラクティス

複数デザイン（スライドマスター）の整理

テンプレートPPTXに複数のスライドマスターが含まれている場合、出力が不安定になることがあります。

確認方法:

python scripts/create_from_template.py assets/template.pptx --list-layouts

対処法:

1. PowerPointでテンプレートを開く
2. [表示] → [スライドマスター] を選択
3. 不要なスライドマスターを削除
4. 保存後、template_layouts.json を再生成

python scripts/analyze_template.py assets/template.pptx

content.json の階層構造

箇条書きに階層構造（インデント）を持たせる場合は items ではなく bullets 形式を使用（items はフラット表示になる）：

{"type": "content", "bullets": [
  {"text": "項目1", "level": 0},
  {"text": "詳細1", "level": 1},
  {"text": "項目2", "level": 0}
]}

Agents

→ references/agents/ for definitions

| Agent | Purpose | | ------------- | --------------------- | | Orchestrator | Pipeline coordination | | Localizer | Translation (EN ↔ JA) | | PPTX Reviewer | Final quality check |

Design Principles

• SSOT: content.json is canonical
• SRP: Each agent/script has one purpose
• Fail Fast: Max 3 retries per phase
• Human in Loop: User confirms at PLAN phase

URL Format in Slides

Reference URLs must use "Title - URL" format for APPENDIX slides:

VPN Gateway の新機能 - https://learn.microsoft.com/ja-jp/azure/vpn-gateway/whats-new

→ references/content-guidelines.md for details

References

| File | Content | | --------------------------------------------------------- | -------------------- | | SCRIPTS.md | Script documentation | | USE_CASES.md | Workflow examples | | content-guidelines.md | URL format, bullets | | agents/ | Agent definitions | | schemas/ | JSON schemas |

Technical Content Addition (Azure/MS Topics)

When adding Azure/Microsoft technical content to slides, follow the same verification workflow as QA:

Workflow

[Content Request] → [Researcher] → [Reviewer] → [PPTX Update]
                         ↓              ↓
                   Docs MCP 検索    内容検証

Required Steps

1. Research Phase: Use microsoft_docs_search / microsoft_docs_fetch to gather official information
2. Review Phase: Verify the accuracy of content before adding to slides
3. Build Phase: Update content.json and regenerate PPTX

Forbidden

• ❌ Adding technical content without MCP verification
• ❌ Skipping review for "simple additions"
• ❌ Generating PPTX while PowerPoint has the file open

File Lock Prevention

Before generating PPTX, check if the file is locked:

# Check if file is locked
$path = "path/to/file.pptx"
try { [IO.File]::OpenWrite($path).Close(); "File is writable" }
catch { "File is LOCKED - close PowerPoint first" }

Shape-based Architecture Diagrams

When creating network/architecture diagrams, use PowerPoint shapes instead of ASCII art text boxes. ASCII art is unreadable in presentation mode.

Design Pattern

from pptx.enum.shapes import MSO_SHAPE
from pptx.dml.color import RGBColor
from pptx.util import Cm, Pt

# Color scheme
AZURE_BLUE = RGBColor(0, 120, 212)
LIGHT_BLUE = RGBColor(232, 243, 255)
ONPREM_GREEN = RGBColor(16, 124, 65)
LIGHT_GREEN = RGBColor(232, 248, 237)

# Outer frame (Azure VNet)
box = slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, left, top, w, h)
box.fill.solid()
box.fill.fore_color.rgb = LIGHT_BLUE
box.line.color.rgb = AZURE_BLUE

# Dashed connector (tunnel)
conn = slide.shapes.add_connector(1, x1, y1, x2, y2)  # 1 = straight
conn.line.color.rgb = AZURE_BLUE
conn.line.dash_style = 2  # dash

Layout Tips

• Use Cm() for positioning (not Inches()) — easier to reason about on metric-based slides
• Leave at least 1.5cm vertical gap between Azure and on-premises zones for tunnel lines
• Place labels inside boxes (not overlapping edges) to avoid visual clutter
• Use color coding to distinguish zones: blue = Azure, green = on-premises, orange = cross-connect
• For dual diagrams (side-by-side), split slide into left/right halves with 12cm left margin for the right diagram

Anti-patterns

❌ ASCII art in textboxes (unreadable in presentation mode)
❌ Overlapping shapes due to insufficient spacing
❌ Placing labels outside their parent containers
❌ Using absolute EMU values without helper functions

Hyperlink Batch Processing

Batch-add hyperlinks and page titles to all URLs in a presentation:

Workflow

import re
url_pattern = re.compile(r'(https?://[^\s\)）]+)')

# 1. Build URL→Title map (use MCP docs_search or fetch_webpage)
URL_TITLES = {
    'https://learn.microsoft.com/.../whats-new': 'Azure VPN Gateway の新機能',
    ...
}

# 2. Iterate all runs and add hyperlinks
for slide in prs.slides:
    for shape in slide.shapes:
        if not shape.has_text_frame:
            continue
        for para in shape.text_frame.paragraphs:
            for run in para.runs:
                urls = url_pattern.findall(run.text)
                for url in urls:
                    if not (run.hyperlink and run.hyperlink.address):
                        run.hyperlink.address = url.rstrip('/')
                    # Prepend title if missing
                    title = URL_TITLES.get(url.rstrip('/'))
                    if title and title not in run.text:
                        run.text = f'{title}\n{url}'

Verification

hlink_count = sum(
    1 for slide in prs.slides
    for shape in slide.shapes if shape.has_text_frame
    for para in shape.text_frame.paragraphs
    for run in para.runs
    if run.hyperlink and run.hyperlink.address
)
print(f'Hyperlinks: {hlink_count}')

Font Theme Token Resolution (ZIP-level)

python-pptx sometimes leaves theme tokens (+mn-ea, +mj-lt) unresolved, causing font fallback. Fix via ZIP-level string replacement:

import zipfile, re, shutil

FONT_JA = 'BIZ UDPゴシック'
FONT_LATIN = 'BIZ UDPGothic'

tmp = out + '.tmp'
shutil.copy2(out, tmp)
with zipfile.ZipFile(tmp, 'r') as zin:
    with zipfile.ZipFile(out, 'w', zipfile.ZIP_DEFLATED) as zout:
        for item in zin.infolist():
            data = zin.read(item.filename)
            if item.filename.endswith('.xml'):
                content = data.decode('utf-8')
                content = content.replace('+mn-ea', FONT_JA)
                content = content.replace('+mj-ea', FONT_JA)
                content = content.replace('+mn-lt', FONT_LATIN)
                content = content.replace('+mj-lt', FONT_LATIN)
                content = re.sub(
                    r'(<a:ea typeface=")[^"]*(")',
                    f'\\g<1>{FONT_JA}\\2', content
                )
                data = content.encode('utf-8')
            zout.writestr(item, data)
os.remove(tmp)

⚠️ Always do this after prs.save(), not before.

Section Management via XML

PowerPoint sections are stored as an extension in ppt/presentation.xml. python-pptx has no native section API.

Adding/Updating Sections

import re, uuid, zipfile

SECTION_URI = '{521415D9-36F7-43E2-AB2F-B90AF26B5E84}'
P14_NS = 'http://schemas.microsoft.com/office/powerpoint/2010/main'

# Read presentation.xml from ZIP
with zipfile.ZipFile(pptx_path) as z:
    pres_xml = z.read('ppt/presentation.xml').decode('utf-8')

# Ensure p14 namespace is declared
if f'xmlns:p14="{P14_NS}"' not in pres_xml:
    pres_xml = pres_xml.replace('<p:presentation',
        f'<p:presentation xmlns:p14="{P14_NS}"', 1)

# Extract slide IDs
slide_ids = re.findall(r'<p:sldId id="(\d+)"', pres_xml)

# Define sections: (name, start_slide_0based)
sections = [("表紙", 0), ("本編", 2), ("Appendix", 15)]

# Build section XML
section_parts = []
for idx, (name, start) in enumerate(sections):
    end = sections[idx+1][1] if idx+1 < len(sections) else len(slide_ids)
    refs = ''.join(f'<p14:sldId id="{slide_ids[i]}"/>'
                   for i in range(start, min(end, len(slide_ids))))
    sec_id = '{' + str(uuid.uuid4()).upper() + '}'
    section_parts.append(
        f'<p14:section name="{name}" id="{sec_id}">'
        f'<p14:sldIdLst>{refs}</p14:sldIdLst></p14:section>'
    )

# Insert into extLst
new_ext = (f'<p:ext uri="{SECTION_URI}">'
           f'<p14:sectionLst xmlns:p14="{P14_NS}">'
           + ''.join(section_parts)
           + '</p14:sectionLst></p:ext>')

# Write back to ZIP

Important Notes

• The URI {521415D9-36F7-43E2-AB2F-B90AF26B5E84} is specific to the presenter's PowerPoint version; some versions use different URIs
• Always remove existing section XML before inserting new ones (avoid duplicates)
• Section changes only show in PowerPoint's slide sorter view after re-opening the file

Slide Layout Change (Safe Pattern)

python-pptx does NOT safely support direct layout swapping. Use the add-move-hide-cleanup pattern:

1. add_slide(target_layout) — new slide at the end
2. Set title text on the new slide's placeholder (placeholder_format.idx == 0)
3. Move new slide to old slide's position via sldIdLst XML manipulation (reverse order)
4. Hide & clear old slide (show='0', remove shapes)
5. Save, re-open, delete hidden slides in a separate pass

# Step 3: Move new slide (last) before old slide
sldIdLst = prs.part._element.find(qn('p:sldIdLst'))
slides_list = list(sldIdLst)
new_el = slides_list[-1]
old_el = list(sldIdLst)[target_idx]
sldIdLst.remove(new_el)
sldIdLst.insert(list(sldIdLst).index(old_el), new_el)

# Step 4: Hide old slide (now at target_idx + 1)
old_slide._element.set('show', '0')
for shape in list(old_slide.shapes):
    shape._element.getparent().remove(shape._element)

Forbidden Patterns (★ Critical)

| Pattern | Problem | Result | |---------|---------|--------| | rel._target = new_layout.part | Layout reference corrupted | PowerPoint repair dialog | | prs.part.drop_rel(rId) for slide deletion | Orphan XML in ZIP | Duplicate name warning → corruption | | show='0' while indices shift | Wrong slides hidden | Content silently disappears |

Safe Hidden Slide Cleanup

Delete hidden slides in a separate script/pass after saving, in reverse index order:

# Cleanup pass (separate from insertion)
prs = Presentation(saved_file)
sldIdLst = prs.part._element.find(qn('p:sldIdLst'))

for i, slide in enumerate(prs.slides):
    if slide._element.get('show') == '0':
        # Verify truly empty before deleting
        has_content = any(
            para.text.strip()
            for shape in slide.shapes if shape.has_text_frame
            for para in shape.text_frame.paragraphs
        )
        if has_content:
            del slide._element.attrib['show']  # Restore, not delete

# Delete empty hidden slides (reverse order)
for idx in reversed(empty_hidden_indices):
    el = list(sldIdLst)[idx]
    rId = el.get(qn('r:id'))
    sldIdLst.remove(el)
    prs.part.drop_rel(rId)

prs.save(output_new_name)  # Always save to NEW filename

Post-Processing (URL Linkification)

⚠️ create_from_template.py does not process footer_url. Post-processing required.

Items Requiring Post-Processing

| Item | Processing | | --------------- | ---------------------------------- | | footer_url | Add linked textbox at slide bottom | | URLs in bullets | Convert to hyperlinks | | Reference URLs | Linkify URLs in Appendix |

Save with Different Name (File Lock Workaround)

PowerPoint locks open files.同名保存は PermissionError になるため、必ず別名で保存：

prs.save('file_withURL.pptx')

| Processing | Suffix | | ------------- | ---------- | | URL added | _withURL | | Final version | _final | | Fixed version | _fixed |

16:9 Slide Centering (Known Issue)

L9: Presentation() のデフォルトプレースホルダは 4:3 (25.4cm) 基準。 slide_width = Cm(33.867) で 16:9 に変更しても プレースホルダ位置は 4:3 のまま → 全スライドが左寄りに表示される。

推奨パターン: Blank + 手動配置

prs = Presentation()
prs.slide_width = Cm(33.867)  # 16:9
prs.slide_height = Cm(19.05)
SW = prs.slide_width

# Blank layout (プレースホルダなし) を使う
slide = prs.slides.add_slide(prs.slide_layouts[6])

# SW 基準で中央配置
margin = Cm(3)
tb = slide.shapes.add_textbox(margin, Cm(5), SW - margin * 2, Cm(3))
p = tb.text_frame.paragraphs[0]
p.text = "Centered Title"
p.alignment = PP_ALIGN.CENTER

Anti-patterns

❌ Layout 0-5 を 16:9 スライドで使う（プレースホルダが 25.4cm 基準で左寄り）
❌ slide_width 変更後にプレースホルダ位置を未調整のまま使う
✅ Blank レイアウト + add_textbox() で SW 基準の対称マージン配置
✅ テンプレート PPTX 自体が 16:9 で作成されていれば Layout 0-5 も OK

Template Corruption Recovery

L10: .gitattributes の *.pptx binary が git add 後 に追加された場合、 CRLF/エンコーディング変換でバイナリが破壊される（UTF-8 replacement char EF BF BD が混入）。

診断方法

with open('template.pptx', 'rb') as f:
    data = f.read()
count = data.count(b'\xef\xbf\xbd')
print(f'UTF-8 replacement chars: {count}')  # 0 以外なら破損

復旧方法

# python-pptx で空テンプレートを再生成
from pptx import Presentation
prs = Presentation()
prs.slide_width = Cm(33.867)  # 16:9
prs.slide_height = Cm(19.05)
prs.save('template_new.pptx')
# → 11 layouts が自動生成される（4:3 プレースホルダ注意）

予防策

• .gitattributes は 最初のコミット前 に設定する
• skill-ninja 等の自動インストーラ経由の場合、.gitignore による除外とバイナリ管理の整合性を確認

Video Embedding (ZIP Direct Manipulation)

L11: python-pptx は公式に MP4 埋め込み非対応。 しかし PPTX は ZIP なので lxml + zipfile で直接操作すれば埋め込み可能。

必要な操作

1. slide XML: p:pic に a:videoFile + p14:media を注入
2. slide rels: video/image リレーションシップを追加 (rId)
3. [Content_Types].xml: <Default Extension="mp4" ContentType="video/mp4"/> を追加
4. ZIP: ppt/media/ に MP4 ファイルとポスター画像を格納

XML パターン

<p:pic>
  <p:nvPicPr>
    <p:cNvPr id="100" name="Video 1">
      <a:hlinkClick r:id="" action="ppaction://media"/>
    </p:cNvPr>
    <p:cNvPicPr><a:picLocks noChangeAspect="1"/></p:cNvPicPr>
    <p:nvPr>
      <a:videoFile r:link="rId10"/>
      <p:extLst>
        <p:ext uri="{DAA4B4D4-6D71-4841-9C94-3DE7FCFB9230}">
          <p14:media r:embed="rId11"/>
        </p:ext>
      </p:extLst>
    </p:nvPr>
  </p:nvPicPr>
  <p:blipFill>
    <a:blip r:embed="rId12"/>  <!-- poster image -->
    <a:stretch><a:fillRect/></a:stretch>
  </p:blipFill>
  <p:spPr>
    <a:xfrm>
      <a:off x="720000" y="1260000"/>
      <a:ext cx="10752120" cy="5058000"/>
    </a:xfrm>
    <a:prstGeom prst="rect"><a:avLst/></a:prstGeom>
  </p:spPr>
</p:pic>

Slide Rels (3 リレーションシップ必要)

<Relationship Id="rId10" Type=".../relationships/video"
              Target="../media/video.mp4" TargetMode="Internal"/>
<Relationship Id="rId11" Type=".../2007/relationships/media"
              Target="../media/video.mp4"/>
<Relationship Id="rId12" Type=".../relationships/image"
              Target="../media/poster.png"/>

注意事項

• PowerPoint が「修復しますか？」と聞く場合がある（軽微な XML 不整合） → 「はい」で自動修復される
• ポスター画像は必須（表示用サムネイル）
• ファイルサイズ注意: 動画を ZIP 圧縮すると PPTX が肥大化。Git 管理には LFS 推奨

Done Criteria

• [ ] content.json generated and validated
• [ ] PPTX file created successfully
• [ ] No text overflow detected
• [ ] User confirmed output quality