PPTX

PPT Master Skill

AI-driven SVG presentation generation system. Turns user requirements, topic prompts, or provided text/Markdown into high-quality editable PPTX decks.

Core Pipeline: Request → Project → Strategist + layout_plan.json → [Images/Video] → SVG composition + [native chart/media data] → Quality Check → Export → Render/Repair

Presentation Quality Contract (Mandatory)

The deck is an audience-facing communication artifact, not a formatted outline. Every generation route MUST apply this contract before selecting layouts:

1. Communication job — record one sentence in design_spec.md: “By the end, [audience] should [outcome] because [central takeaway].” Infer sensible defaults from the request; ask only when a missing choice would materially change the result.
2. Narrative arc — use a cumulative arc appropriate to the job, such as context → stakes → evidence → implications → action; problem → options → recommendation; or current state → change → future state. An agenda alone is not a narrative.
3. One claim per slide — each page has one narrative job and a concise, takeaway-style title. Adjacent slides should answer or advance the question raised by the prior slide. Open deliberately and close with a decision, synthesis, implication, or next action rather than a generic “Thank you.”
4. Audience-facing copy — never expose production notes, prompt scaffolds, design deliberation, or model instructions on the canvas. Put presenter-only material in speaker notes.
5. Density and typography — shorten or split content before reducing type. Use at least 67 px for deck titles (≈50 pt), 47 px for slide titles (≈35 pt), 32 px for subheads (≈24 pt), and 22 px for every audience-facing body or label (exports safely above 16 pt). Only footer/legal text in the bottom 12% of the canvas may be smaller. A reference template may preserve its style, but its non-footer text must still meet these delivery minimums. A title intended as one line must not wrap. Read references/text-role-system.md and design a page-specific role grammar rather than repeating only title, body, and boxed labels. Read references/typography-profiles.md and select one profile from templates/layouts/typography_profiles.json; ordinary unbranded business decks default to office-modern, not the more web-like product-modern. Premium slides declare at least three text roles in layout_plan.json and on the SVG root.
6. Visual composition — use one coherent composition, not a dashboard of repeated cards, pills, tabs, or UI panels. Vary adjacent silhouettes by content role. Use diagrams only when they materially clarify a relationship or sequence.
7. Provenance — every externally sourced non-trivial claim and asset must be traceable. Add a [Sources] block with exact URLs to that slide's speaker notes; never invent citations.
8. Final-output QA — SVG validation is necessary but not sufficient. After exporting the native PPTX, render every final slide through LibreOffice, inspect each slide at full size, and fix unintended overlap, clipping, wrapping, font substitution, broken connectors, unresolved placeholders, inconsistent page markers, and chart/data mismatches before delivery.

Generation methods — the default is the editable-SVG pipeline below. An optional Full-Page Image mode (workflows/image-mode.md) keeps the same page-by-page SVG composition and validation discipline, then rasterizes every validated page into one full-slide image. AI generation may supply text-free visual assets, but exact text, charts, tables, and diagrams are authored in SVG before rasterization. The final deck is not editable, but image-model typography is forbidden. Image mode is explicit opt-in only — enter it only when the user asks for it (e.g. "整页图片模式 / image mode / 每页直接用图片生成") or when Manor invokes this built-in skill with structured params.render == "full_page_image".

Manor Built-In Skill Compatibility

This package is the built-in pptx skill, mounted in the sandbox at /skill/.

• Treat /skill as SKILL_DIR. Before running commands, use cd /skill and set SKILL_DIR=/skill when needed.
• Use /skill/projects/... for generated project folders unless the user asks for a different writable path.
• Final PPTX files are expected under /skill/projects/<project>/exports/; save the final artifact from there.
• Do not require external image-generation credentials inside the built-in skill. For Acquire Via: ai rows, create images/image_prompts.json, render images/image_prompts.md with ${SKILL_DIR}/scripts/image_prompts.py --render-md, call Manor's system image tool with generate_file(kind="image"), then call the outer sandbox_write_file tool with the returned workspace_path and an absolute destination under <project_path>/images/. Use ${SKILL_DIR}/scripts/import_system_image.py only when the generated asset is actually mounted under /workspace.
• Do not use local image-provider backends from this skill. The built-in package has no local AI image generation entry point; use ${SKILL_DIR}/scripts/image_prompts.py only for prompt manifest bookkeeping.
• User-provided video attachments exposed under /workspace are supported as embedded presentation assets. Copy each selected clip into <project_path>/media/, probe it with ffprobe, and follow workflows/embedded-media.md. Do not reference /workspace directly from embedded_media.json, because delivery verification must be reproducible from the project folder.

Mandatory Pipeline Evidence

Scope: the serial authoring, layout-plan, SVG, and quality rules in this section govern both output modes. The opt-in Full-Page Image mode (workflows/image-mode.md) replaces only the editable finalize_svg.py / svg_to_pptx.py export path with validated SVG → PNG → images_to_pptx.py. Follow that workflow's evidence checklist when it is selected.

• This skill has no direct-PPTX helper path. Do not write a custom Python, Node, or shell script that constructs a presentation directly.
• Final PPTX output must be produced from hand-written SVG pages through the PPT Master pipeline.
• Required pipeline evidence before saving the final PPTX:
  1. Project initialized with ${SKILL_DIR}/scripts/project_manager.py init <project_name>.
  2. Strategist outputs exist: <project_path>/design_spec.md and <project_path>/spec_lock.md.
  3. <project_path>/layout_plan.json exists, follows references/layout-contract.md, and passes scripts/layout_plan.py.
  4. Executor SVG pages exist under <project_path>/svg_output/, written sequentially by the main agent. Quantitative chart pages also declare real PowerPoint charts in native_charts.json; read workflows/native-charts.md. Slides with playable video reserve data-video-slot regions and declare real PowerPoint media objects in embedded_media.json; read workflows/embedded-media.md.
  5. Quality checks have run with layout_plan.py and ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> and have 0 errors.
  6. Post-processing/export commands have run in order: total_md_split.py, finalize_svg.py, then svg_to_pptx.py.
  7. The saved .pptx comes from <project_path>/exports/ and was generated by svg_to_pptx.py.
  8. The final native PPTX was rendered with render_pptx.py; every rendered slide was inspected at full size and the QA result recorded in <project_path>/qa/final-render.txt.
  9. pptx_quality_gate.py passed with score 90 or higher and wrote <project_path>/qa/pptx-quality.json. A failed machine gate is a hard stop: fix, re-export, re-render, and rerun the gate before delivery.

sandbox_save_result reruns this gate server-side for every PPTX in /skill/projects/<project>/exports/. It verifies all-slide render evidence and binds the report to the exact PPTX bytes by SHA-256. Missing, failing, stale, or manually copied evidence cannot be delivered; renaming the output does not bypass the check.

[!CAUTION]

🚨 Global Execution Discipline (MANDATORY)

This workflow is a strict serial pipeline. The following rules have the highest priority — violating any one of them constitutes execution failure:

1. SERIAL EXECUTION — Steps MUST be executed in order; the output of each step is the input for the next. Non-BLOCKING adjacent steps may proceed continuously once prerequisites are met, without waiting for the user to say "continue"
2. BLOCKING = MATERIAL CHOICE ONLY — Pause only when missing information would materially change scope, brand identity, source fidelity, or the requested output mode. Ordinary topic-only requests use recommended defaults and continue.
3. NO CROSS-PHASE BUNDLING — Cross-phase bundling is FORBIDDEN. Once the design contract is resolved—automatically for ordinary requests or explicitly for a material choice—all subsequent non-BLOCKING steps may proceed without further confirmation.
4. GATE BEFORE ENTRY — Each Step has prerequisites (🚧 GATE) listed at the top; these MUST be verified before starting that Step
5. NO SPECULATIVE EXECUTION — "Pre-preparing" content for subsequent Steps is FORBIDDEN (e.g., writing SVG code during the Strategist phase)
6. NO SUB-AGENT SVG GENERATION — Executor Step 6 SVG generation is context-dependent and MUST be completed by the current main agent end-to-end. Delegating page SVG generation to sub-agents is FORBIDDEN
7. SEQUENTIAL PAGE GENERATION ONLY — In Executor Step 6, after the global design context is confirmed, SVG pages MUST be generated sequentially page by page in one continuous pass. Grouped page batches (for example, 5 pages at a time) are FORBIDDEN
8. SPEC_LOCK RE-READ PER PAGE — Before generating each SVG page, Executor MUST read_file <project_path>/spec_lock.md. All colors / fonts / icons / images MUST come from this file — no values from memory or invented on the fly. Executor MUST also look up the current page's page_rhythm (anchor / dense / breathing), page_layouts (which template SVG to inherit, if any), and page_charts (which chart template to adapt, if any). Empty / absent entries are intentional Strategist signals — see executor-base.md §2.1. This rule exists to resist context-compression drift on long decks and to break the uniform "every page is a card grid" default
9. SVG MUST BE HAND-WRITTEN, NOT SCRIPT-GENERATED — Every SVG page is written by the main agent directly, one page at a time (see rules 6 and 7). Writing or running a Python / Node / shell script that produces the SVG files in batch — looping over pages, templating from data, or emitting them via a generator — is FORBIDDEN, including under "save tokens", "quick draft", or "user is in a hurry" pretexts. The script-generation path was tried on a feature branch and abandoned: cross-page visual consistency depends on per-page authoring with full upstream context, which a generator script cannot reproduce

[!IMPORTANT]

🌐 Language & Communication Rule

• Response language: match the user's input and source materials. Explicit user override (e.g., "请用英文回答") takes precedence.
• Template format: design_spec.md MUST follow its original English template structure (section headings, field names) regardless of conversation language. Content values may be in the user's language.

[!IMPORTANT]

🔌 Compatibility With Generic Coding Skills

• ppt-master is a repository-specific workflow, not a general application scaffold
• In this built-in package, invoke it through the pptx skill name.
• Do NOT create .worktrees/, tests/, branch workflows, or generic engineering structure by default
• On conflict with a generic coding skill, follow this skill unless the user explicitly says otherwise

Main Pipeline Scripts

For complete tool documentation, see ${SKILL_DIR}/scripts/README.md.

Template Index

Diagram Guidance

When a slide needs a process map, architecture diagram, relationship diagram, matrix, funnel, timeline, or custom infographic, load references/blocks/editable-diagram.md. Diagram output must remain editable with native PPTX shapes/connectors/text after export, not a flattened raster image. Existing diagram block guidance lives at references/blocks/diagram.md and defers to the editable-diagram rules. Logical SVG edges must use data-connector="true"; diagram nodes and panels must use data-connector-obstacle="true". The SVG gate rejects edges that cross text, enter protected shapes, cross other connectors, render above nodes, or fail to terminate on a visible shape boundary.

Before choosing a diagram, write the relationship as one sentence and select a single topology. A hub-and-spoke is valid only for genuinely symmetric peer relationships around one hub. Intake → controls → execution with audit or evidence feedback is a governed pipeline, not a radial diagram.

Standalone Workflows

Workflow

Step 1: Request Intake

🚧 GATE: User has provided a topic, requirements, outline, text, or Markdown content.

Use the invocation prompt and any provided text/Markdown directly as the source material. A user-provided .pptx is a supported visual reference: carry its path into Step 3 and follow workflows/follow-reference-pptx.md. This built-in skill does not install or run PDF, DOC, Excel, URL, or legacy .ppt conversion pipelines. If the user supplies only a topic, create the deck from that topic and the model's general knowledge unless the user explicitly provides source text.

Browser-based live preview cannot render EMF (will show blank) — this is expected; the PPTX output is the source of truth.

✅ Checkpoint — Confirm source content is ready, proceed to Step 2.

Step 2: Project Initialization

🚧 GATE: Step 1 complete; source content is ready (Markdown file, user-provided text, or requirements described in conversation are all valid).

python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --format <format>

The canonical project directory includes the canvas format and date. Capture the exact path printed after Project created: and use that path for every later command, file write, quality check, and sandbox_save_result call. Never reconstruct or guess it from <project_name>. Initialization also creates a projects/<project_name> compatibility symlink, but the printed canonical path remains the source of truth for delivery evidence.

Format options: ppt169 (default), ppt43, xhs, story, etc. For the full format list, see references/canvas-formats.md.

Use the user's prompt and any provided text/Markdown directly as the source context. Do not run source import or conversion commands in the built-in generation path.

✅ Checkpoint — Confirm project structure created successfully and the source context is available from the invocation prompt/conversation. Proceed to Step 3.

Step 3: Template Option

🚧 GATE: Step 2 complete; project directory structure is ready.

Choose exactly one visual route. The first matching route wins:

1. User-provided PPTX or explicit template directory — treat it as the visual source of truth. Reuse its page hierarchy, layouts, typography, and media frames; do not mix in an unrelated built-in template.
2. Explicit custom direction without a reference deck — create a custom system from the requested brand, theme, mood, or formatting brief.
3. No visual direction — query layouts_index.json and automatically shortlist unbranded layouts by semantic role: cover, statement, comparison, process, timeline, evidence, chart, table, and closing action. Preserve the selected layout's hierarchy and vary adjacent page silhouettes. Do not wait for the user to choose a filesystem path.

A bare unbranded template name may be resolved through layouts_index.json. Never automatically apply a branded layout or logo from a brand mention alone. Branded templates and brand bundles require either an explicit directory path or supplied brand assets.

When the reference is a .pptx, load workflows/follow-reference-pptx.md, then prepare the hierarchy-aware reference workspace before Strategist begins:

python3 ${SKILL_DIR}/scripts/pptx_template_import.py \
  <reference.pptx> --output <project_path>/reference \
  --inheritance-mode both

Read reference/manifest.json, every master/layout/slide SVG, the inheritance graph, and every flattened slide at full size. Record the selected reference family for every new page in spec_lock.page_layouts. If the import exposes an unsupported source object, report and reconstruct it deliberately; never silently replace the reference with a generic built-in layout.

For an explicit template directory, copy the exact bundle into the project:

TEMPLATE_DIR=<user-supplied path>
cp ${TEMPLATE_DIR}/*.svg <project_path>/templates/
cp ${TEMPLATE_DIR}/design_spec.md <project_path>/templates/
cp ${TEMPLATE_DIR}/*.png <project_path>/images/ 2>/dev/null || true
cp ${TEMPLATE_DIR}/*.jpg <project_path>/images/ 2>/dev/null || true

To create a new template, read workflows/create-template.md.

An explicit brand directory contributes color, typography, logo, voice, and icon treatment. Copy it without flattening its assets:

BRAND_DIR=<user-supplied brand path>
cp ${BRAND_DIR}/design_spec.md <project_path>/templates/
cp ${BRAND_DIR}/*.svg <project_path>/templates/ 2>/dev/null || true     # brand logo SVG files
cp ${BRAND_DIR}/*.png <project_path>/templates/ 2>/dev/null || true     # brand logo raster files
[ -d ${BRAND_DIR}/images ] && cp -r ${BRAND_DIR}/images <project_path>/templates/
[ -d ${BRAND_DIR}/illustrations ] && cp -r ${BRAND_DIR}/illustrations <project_path>/templates/
[ -d ${BRAND_DIR}/icons ] && cp -r ${BRAND_DIR}/icons <project_path>/templates/

To create a new brand, read workflows/create-brand.md.

Brand + layout combined input

A brand path and a layout template path may both be supplied in the same message. When both are present, Step 3 fuses them into a single design_spec.md inside <project_path>/templates/ instead of leaving two specs side by side. Field-level precedence is fixed (no per-deck prompting):

Action: AI reads ${LAYOUT_DIR}/design_spec.md and ${BRAND_DIR}/design_spec.md, composes one fused design_spec.md using the table above, writes it to <project_path>/templates/design_spec.md. SVG page files come from ${LAYOUT_DIR}; brand logos and asset subdirectories from ${BRAND_DIR}. The fused spec carries a one-line > Fused from: layout=<layout_id>, brand=<brand_id> provenance note under its H1.

Conflict gates — clarify with the user only in these two cases:

1. Brand has no logo, layout has one. Ask: "your brand has no bundled logo; use the layout's logo, or leave the deck logo-less?"
2. Layout is itself a branded template (e.g. 招商银行, 重庆大学, 中汽研_*, 中国电建_*) and the supplied brand is different. Ask: "this layout carries <layout's own brand> identity, which conflicts with the <supplied brand> you provided — confirm you want brand identity from <supplied brand> and only the page structure from <layout>?"

If neither gate trips, fusion proceeds silently and Step 3 advances.

✅ Checkpoint — Visual route selected and its constraints recorded. Ordinary topic-only requests now have a semantic layout shortlist; explicit reference or brand bundles are copied or fused before advancing.

Step 4: Strategist Phase (MANDATORY — cannot be skipped)

🚧 GATE: Step 3 complete; default free-design path taken, or (if triggered) template files copied into the project.

First, read the role definition:

Read references/strategist.md

⚠️ Mandatory gate: before writing design_spec.md, Strategist MUST read_file templates/design_spec_reference.md and follow its full I–XI section structure. See strategist.md Section 1.

Eight Design Decisions (full template: templates/design_spec_reference.md):

Resolve these as a single recommended design contract. For an ordinary request, infer sensible defaults, record them in the spec, briefly tell the user what was chosen, and continue without stopping. Ask for confirmation only when a missing choice would materially alter scope, brand identity, reference fidelity, or the editable versus full-page-image output mode.

1. Canvas format
2. Page count range
3. Target audience
4. Style objective
5. Color scheme
6. Icon usage approach
7. Typography plan
8. Image and video usage approach

Split-mode note (not a ninth decision): include one short line, rendered in the user's language and prefixed with 💡, only for a heavy deck or when a context window switch would materially improve execution quality.

If the user provided images, run analysis before outputting the design spec:

python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images

⚠️ Image handling: run analyze_images.py for objective dimensions and metadata, then inspect every selected image and its final crop at slide size with the available image-viewing tool. Replace blurry, distorted, badly framed, text-corrupted, or visually inconsistent assets before export.

If the user provided video, inspect its filename, duration, dimensions, and codec with ffprobe, then list it in the design spec's media resource section. Do not fabricate or fetch video implicitly. A missing user-supplied clip is recorded as Needs-Manual, not silently replaced with a screenshot.

Output:

• <project_path>/design_spec.md — human-readable design narrative
• <project_path>/spec_lock.md — machine-readable execution contract (skeleton: templates/spec_lock_reference.md); Executor re-reads before every page
• <project_path>/layout_plan.json — one structured page composition per slide; read references/layout-contract.md, shortlist from templates/layouts/composition_registry.json, and validate before Executor begins

✅ Checkpoint — Phase deliverables complete, auto-proceed to next step:

## ✅ Strategist Phase Complete
- [x] Eight design decisions resolved (recommended defaults or explicit confirmation)
- [x] Communication job and narrative arc recorded
- [x] Split-mode note included only when materially useful
- [x] Design Specification & Content Outline generated
- [x] Execution lock (spec_lock.md) generated
- [x] Structured layout plan generated and validated
- [ ] **Next**: Auto-proceed to [Image_Generator / Executor] phase