| name | azure-pptx |
| description | Use this skill any time a .pptx file is involved — as input, output, or both. This includes creating, reading, editing, or modifying presentations. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx filename. This project uses the Microsoft Azure PowerPoint Template (Light). |
| license | Proprietary. LICENSE.txt has complete terms |
PPTX Skill
出自: Anthropic PPTX Skill をベースに、プロジェクト固有のルールを追加。
「📌」マークのあるセクションは本リポジトリ専用のルールであり、ベーススキルには含まれない。
Quick Reference
Reading Content
uv run python -m markitdown presentation.pptx
uv run scripts/thumbnail.py presentation.pptx
uv run scripts/office/unpack.py presentation.pptx unpacked/
Editing Workflow
Read references/editing.md for full details.
- Analyze template with
thumbnail.py
- Unpack → manipulate slides → edit content → clean → pack
This project uses the Azure template. Read references/azure-template.md for template-specific details (fonts, layout indices, placeholder mappings, bullet rules). 📌
📌 このプロジェクト固有の制約
.pptx を新規作成・編集する場合、Microsoft Azure PowerPoint Template (Light) の利用は必須- テンプレートを使わずにゼロから組む案を、通常案として選んではならない
- テンプレート未使用の
.pptx を作った時点で、このプロジェクトでは要件未達
- 「まずテンプレートなしで作って、あとで整える」という進め方も不可
補足: python-pptx / pptxgenjs の利用について
上記で禁止しているのは「テンプレートを使わずにゼロから作る」ことであり、ツール自体の利用ではない。
- ✅ python-pptx で テンプレート .potx/.pptx を開いて スライドを編集・追加・削除する → テンプレート利用
- ❌ python-pptx で
Presentation() を空から作る → テンプレート未使用
- ❌ pptxgenjs で独自デザインのスライドを生成する → テンプレート未使用
📌 例外
次の場合に限り、テンプレート未使用案を検討してよい。
- ユーザーがテンプレート不要と明示した場合
- 既存テンプレートでは物理的に表現できず、代替案の検討をユーザーが明示的に求めた場合
上記以外では、テンプレート未使用案を自分の判断で採用しない。
📌 実装前チェック
スライド作成を始める前に、少なくとも次を確定すること。
- どの Azure template layout を使うか
- 画像中心のスライドか、画像 + 本文の併置か
- 図表や外部画像を使う場合、それが 1 スライドで読めるか
- 読めない場合、画像埋め込みを諦めて別資料参照に切り替えるか
この確認をせずに「作りやすい方法」で新規生成へ進まないこと。
📌 このリポジトリで得た運用メモ
- Azure template 固有のレイアウト選択、Thank you の使い方、draw.io 図の貼り込み方は
references/azure-template.md に追記して管理する
- 概要図が大きすぎて 1 スライドで読めない場合、図の貼り込みを必須にしない。スライドには要点だけを載せ、図は別資料参照に切り替えてよい
SKILL.md には「いつ template を使うか」「どういう順序で進めるか」の方針だけを書き、個別レイアウトの運用詳細は持ち込まない- 初回出力をそのまま完成扱いにしない。
markitdown と soffice -> pdftoppm の両方で内容と見た目を確認してから仕上げる
📌 テンプレートから新規作成
テンプレートをベースに新規プレゼンテーションを作る場合、XML 直接操作ではなく python-pptx を使う。
なぜ XML 直接操作ではなく python-pptx か: テンプレートの XML 構造にはスライド間の相互参照（sldIdLst、p14:sectionLst、presentation.xml.rels）が多数含まれる。XML 直接操作でスライドを削除すると孤児参照が残り、PowerPoint が破損と判定する。python-pptx はこれらの参照を内部で管理するため、生 XML 操作より安全である。ただし、以下のスライド削除コードは _sldIdLst 等の private API に依存するため、python-pptx のバージョン更新時には動作確認が必要。
手順
- テンプレートを .pptx に変換:
.potx を zip として開き、[Content_Types].xml 内の presentationml.template.main+xml を presentationml.presentation.main+xml に置換して .pptx として保存
- python-pptx で開く:
Presentation('template.pptx') でスライドマスター・レイアウトを含む状態で開く
- 不要スライドを削除: テンプレートのサンプルスライドを削除（下記コード参照）
- 新規スライドを追加:
prs.slide_layouts[N] からレイアウトを選び、prs.slides.add_slide(layout) で追加
- コンテンツを設定: プレースホルダにテキスト・表・画像を挿入
- 保存:
prs.save('output.pptx')
python-pptx でのスライド削除
def delete_slide(prs, slide_index):
"""指定インデックスのスライドを削除する。"""
rId = prs.slides._sldIdLst[slide_index].get(
"{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id"
)
prs.part.drop_rel(rId)
del prs.slides._sldIdLst[slide_index]
for i in range(len(prs.slides) - 1, -1, -1):
delete_slide(prs, i)
Creating from Scratch
📌 このリポジトリでは例外時のみ使用。 Azure template 利用が前提のため、ユーザーが明示的に例外を認めた場合のみ使う。
Read references/pptxgenjs.md for full details.
📌 スライドコンテンツのルール
言葉遣い
- 「ベストプラクティス」「自動」などの曖昧・冗長な表現を避け、具体的に何をどうするかを書く
- AIエージェントの動作として当然のこと（生成、取得、分析など）に「自動」は付けない
- 曖昧な用語は具体的な対象に置き換える（例: 「ベストプラクティス」→「Bicepスキーマ」「サービス推奨構成」）
ツール・機能の出所を明記する
📌 Copilot CLI / MCP ツール紹介スライドを作る場合のルール。一般的なアーキテクチャ資料や業務資料には機械的に適用しない。
- ツールや機能をスライドで説明する際は、提供元を必ず明記する
- Azure MCP Server のツール（aks, bicepschema, applens 等）
- MS Learn MCP Server のツール（microsoft_docs_search, code_sample_search 等）
- Copilot CLI 組み込み機能（/research, /model, /skills 等）
- Copilot CLI Skill（azure-pptx, azure-drawio 等）
- グループヘッダ（太字）＋インデントされたサブ項目で構造化する
- ツール名だけ列挙せず、何ができるかを添える（例: 「applens」→「applens（「問題の診断と解決」機能）で問題を検出」）
聴衆視点での検証
- スライドを書く際は「聴衆がこれを見て理解できるか？次に何を知りたいか？」を考慮する
- 抽象的な説明には具体例（ツール名、コマンド例、ユースケース）を添える
- 専門用語やサービス名が初出の場合は、何であるかを補足する
スライド構成・順序
- 同じカテゴリ・テーマのスライドは隣接させる
- スライドの追加・移動後は、孤立したスライドがないか全体を確認する
- 前のスライドで言及した概念が、後のスライドで説明される順序を意識する
Design Ideas
📌 テンプレート利用時の注意: Azure template はブランドカラー（Azure Blue 系）・フォント（Segoe UI）が固定されている。以下の Color Palettes / Typography セクションはテンプレート未使用時（pptxgenjs）の参考であり、Azure template 利用時はテンプレートのスタイルに従うこと。レイアウト指針・スペーシング・Data display の考え方は参考にしてよい。
Don't create boring slides. Plain bullets on a white background won't impress anyone. Consider ideas from this list for each slide.
Before Starting
- Pick a bold, content-informed color palette: The palette should feel designed for THIS topic. If swapping your colors into a completely different presentation would still "work," you haven't made specific enough choices.
- Dominance over equality: One color should dominate (60-70% visual weight), with 1-2 supporting tones and one sharp accent. Never give all colors equal weight.
- Dark/light contrast: Dark backgrounds for title + conclusion slides, light for content ("sandwich" structure). Or commit to dark throughout for a premium feel.
- Commit to a visual motif: Pick ONE distinctive element and repeat it — rounded image frames, icons in colored circles, thick single-side borders. Carry it across every slide.
Color Palettes
Choose colors that match your topic — don't default to generic blue. Use these palettes as inspiration:
| Theme | Primary | Secondary | Accent |
|---|
| Midnight Executive | 1E2761 (navy) | CADCFC (ice blue) | FFFFFF (white) |
| Forest & Moss | 2C5F2D (forest) | 97BC62 (moss) | F5F5F5 (cream) |
| Coral Energy | F96167 (coral) | F9E795 (gold) | 2F3C7E (navy) |
| Warm Terracotta | B85042 (terracotta) | E7E8D1 (sand) | A7BEAE (sage) |
| Ocean Gradient | 065A82 (deep blue) | 1C7293 (teal) | 21295C (midnight) |
| Charcoal Minimal | 36454F (charcoal) | F2F2F2 (off-white) | 212121 (black) |
| Teal Trust | 028090 (teal) | 00A896 (seafoam) | 02C39A (mint) |
| Berry & Cream | 6D2E46 (berry) | A26769 (dusty rose) | ECE2D0 (cream) |
| Sage Calm | 84B59F (sage) | 69A297 (eucalyptus) | 50808E (slate) |
| Cherry Bold | 990011 (cherry) | FCF6F5 (off-white) | 2F3C7E (navy) |
For Each Slide
Every slide needs a visual element — image, chart, icon, or shape. Text-only slides are forgettable.
Layout options:
- Two-column (text left, illustration on right)
- Icon + text rows (icon in colored circle, bold header, description below)
- 2x2 or 2x3 grid (image on one side, grid of content blocks on other)
- Half-bleed image (full left or right side) with content overlay
Data display:
- Large stat callouts (big numbers 60-72pt with small labels below)
- Comparison columns (before/after, pros/cons, side-by-side options)
- Timeline or process flow (numbered steps, arrows)
Visual polish:
- Icons in small colored circles next to section headers
- Italic accent text for key stats or taglines
Typography
Choose an interesting font pairing — don't default to Arial. Pick a header font with personality and pair it with a clean body font.
| Header Font | Body Font |
|---|
| Georgia | Calibri |
| Arial Black | Arial |
| Calibri | Calibri Light |
| Cambria | Calibri |
| Trebuchet MS | Calibri |
| Impact | Arial |
| Palatino | Garamond |
| Consolas | Calibri |
| Element | Size |
|---|
| Slide title | 36-44pt bold |
| Section header | 20-24pt bold |
| Body text | 14-16pt |
| Captions | 10-12pt muted |
Spacing
- 0.5" minimum margins
- 0.3-0.5" between content blocks
- Leave breathing room—don't fill every inch
Avoid (Common Mistakes)
- Don't repeat the same layout — vary columns, cards, and callouts across slides
- Don't center body text — left-align paragraphs and lists; center only titles
- Don't skimp on size contrast — titles need 36pt+ to stand out from 14-16pt body
- Don't default to blue — pick colors that reflect the specific topic
- Don't mix spacing randomly — choose 0.3" or 0.5" gaps and use consistently
- Don't style one slide and leave the rest plain — commit fully or keep it simple throughout
- Don't create text-only slides — add images, icons, charts, or visual elements; avoid plain title + bullets
- Don't forget text box padding — when aligning lines or shapes with text edges, set
margin: 0 on the text box or offset the shape to account for padding
- Don't use low-contrast elements — icons AND text need strong contrast against the background; avoid light text on light backgrounds or dark text on dark backgrounds
- NEVER use accent lines under titles — these are a hallmark of AI-generated slides; use whitespace or background color instead
QA (Required)
Assume there are problems. Your job is to find them.
Your first render is almost never correct. Approach QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you weren't looking hard enough.
Content QA
uv run python -m markitdown output.pptx
Check for missing content, typos, wrong order.
When using templates, check for leftover placeholder text:
uv run python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|this.*(page|slide).*layout"
If grep returns results, fix them before declaring success.
Visual QA
⚠️ USE SUBAGENTS — even for 2-3 slides. You've been staring at the code and will see what you expect, not what's there. Subagents have fresh eyes.
Convert slides to images (see Converting to Images), then use this prompt:
Visually inspect these slides. Assume there are issues — find them.
Look for:
- Overlapping elements (text through shapes, lines through words, stacked elements)
- Text overflow or cut off at edges/box boundaries
- Decorative lines positioned for single-line text but title wrapped to two lines
- Source citations or footers colliding with content above
- Elements too close (< 0.3" gaps) or cards/sections nearly touching
- Uneven gaps (large empty area in one place, cramped in another)
- Insufficient margin from slide edges (< 0.5")
- Columns or similar elements not aligned consistently
- Low-contrast text (e.g., light gray text on cream-colored background)
- Low-contrast icons (e.g., dark icons on dark backgrounds without a contrasting circle)
- Text boxes too narrow causing excessive wrapping
- Leftover placeholder content
For each slide, list issues or areas of concern, even if minor.
Read and analyze these images:
1. /path/to/slide-01.jpg (Expected: [brief description])
2. /path/to/slide-02.jpg (Expected: [brief description])
Report ALL issues found, including minor ones.
Verification Loop
- Generate slides → Convert to images → Inspect
- List issues found (if none found, look again more critically)
- Fix issues
- Re-verify affected slides — one fix often creates another problem
- Repeat until a full pass reveals no new issues
Do not declare success until you've completed at least one fix-and-verify cycle.
Converting to Images
Convert presentations to individual slide images for visual inspection:
uv run scripts/office/soffice.py --headless --convert-to pdf output.pptx
pdftoppm -jpeg -r 150 output.pdf slide
This creates slide-01.jpg, slide-02.jpg, etc.
To re-render specific slides after fixes:
pdftoppm -jpeg -r 150 -f N -l N output.pdf slide-fixed
Dependencies
📌 このリポジトリでは pip を直接使わない。 uv add（プロジェクト依存）/ uv pip install（グローバル）/ PEP 723 インラインメタデータ（単一ファイルスクリプト）で管理すること。以下は必要なパッケージの一覧であり、インストールコマンドはリポジトリの規約に従う。
markitdown[pptx] — text extraction（xlsx 読み取りには追加で openpyxl が必要）Pillow — thumbnail gridsdefusedxml — XML parsing（office scripts 全般で使用）lxml — XML validation and schema checking（validators で使用）pptxgenjs（npm） — creating from scratch- LibreOffice (
soffice) — PDF conversion (via scripts/office/soffice.py)
- Poppler (
pdftoppm) — PDF to image conversion
