Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(template-workspaces): align portable template routing

hugohe37c90b47b8ce7
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index eb253165..8c0ec9e7 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -219,7 +219,7 @@ Multi-deck: several PPTX files may be imported into one main-pipeline project
**Default — free design.** Proceed directly to Step 4. Do NOT query any `*_index.json` unless triggered. Do NOT ask the user. Do NOT proactively suggest, hint at, or fuzzy-match any template based on content, slug-like words, or vague style descriptions.
-**Hard boundary — raw PPTX template references are not Step 3 templates.** PPTX-as-source remains valid in Step 1 / Step 2, and raw PPTX template + generated PPTX routes to `template-fill`. But if the user wants the SVG/template-based generation route from that PPTX, stop before Step 3. The user must first run [`workflows/create-template.md`](workflows/create-template.md), then return with the generated template workspace path. Step 3 consumes an explicit workspace whose `templates/design_spec.md` declares `kind: layout` / `kind: deck`, a direct brand package, or a legacy flat package whose root `design_spec.md` declares one of those kinds.
+**Hard boundary — raw PPTX template references are not Step 3 templates.** PPTX-as-source remains valid in Step 1 / Step 2, and raw PPTX template + generated PPTX routes to `template-fill`. But if the user wants the SVG/template-based generation route from that PPTX, stop before Step 3. The user must first run [`workflows/create-template.md`](workflows/create-template.md), then return with the generated template workspace path. Step 3 consumes an explicit workspace whose `templates/design_spec.md` declares `kind: brand` / `kind: layout` / `kind: deck`, or a compatible legacy-flat package whose root `design_spec.md` declares one of those kinds.
Do **not** reinterpret this boundary as 1:1 redesign or free SVG generation. Use `template-fill` for raw PPTX template + generated PPTX requests; use `beautify` only when the source deck's page count, order, and wording are preserved.
@@ -227,7 +227,7 @@ Do **not** reinterpret this boundary as 1:1 redesign or free SVG generation. Use
| User input contains | Step 3 action |
|---|---|
-| One or more explicit template workspace paths (each resolves to `templates/design_spec.md`, or to a legacy/direct root `design_spec.md`, with `kind: brand` / `kind: layout` / `kind: deck` in YAML frontmatter) | Normalize each source directory, read its `kind`, dispatch per the kind matrix below, fuse if multiple |
+| One or more explicit template workspace paths (each resolves to `templates/design_spec.md`, or to a compatible legacy-flat root `design_spec.md`, with `kind: brand` / `kind: layout` / `kind: deck` in YAML frontmatter) | Normalize each source directory, read its `kind`, dispatch per the kind matrix below, fuse if multiple |
| Current `create-template` workflow just completed project scope and validated its exact `<project>/` workspace | Consume that single workspace in place; it cannot join multi-path fusion |
| Anything else — bare template names ("用 academic_defense"), style descriptions ("麦肯锡风格"), brand mentions ("招商银行风格"), vague intent ("想用个模板"), or silence | Skip Step 3, free design |
@@ -249,7 +249,7 @@ The architecture has three independent reference bundles. Full schema in [`docs/
| Kind | Physical dir | Contains | Frontmatter |
|---|---|---|---|
-| **brand** | `templates/brands/<id>/` (direct package; `create-brand` contract) | identity-only segment: color / typography / logo / voice / icon style | `kind: brand` |
+| **brand** | `templates/brands/<id>/templates/` inside a complete workspace | identity-only segment: color / typography / logo / voice / icon style | `kind: brand` |
| **layout** | `templates/layouts/<id>/templates/` inside a complete workspace | structure-only segment: canvas / page structure / page types / SVG roster | `kind: layout` |
| **deck** | `templates/decks/<id>/templates/` inside a complete workspace | full replica: identity + structure + middle (template overview) segments | `kind: deck` |
@@ -265,27 +265,26 @@ The architecture has three independent reference bundles. Full schema in [`docs/
| User path's `kind` | Step 3 action |
|---|---|
-| `kind: brand` | Install the direct package's spec/non-image assets in `<project>/templates/` and bitmaps in `<project>/images/`. Strategist locks identity; structure stays free. |
-| `kind: layout` | Install the workspace's `templates/`, `images/`, and `icons/` into the matching project roots; ignore `exports/`. Strategist locks structure; identity is decided in confirmation fields e–g. |
-| `kind: deck` | Install the workspace's `templates/`, `images/`, and `icons/` into the matching project roots; ignore `exports/`. Strategist locks all segments; confirmation narrows to deck-content fields. |
+| `kind: brand` | Install `templates/` plus any existing `images/` and `icons/` into the matching project roots; ignore `exports/`. Strategist locks identity; structure stays free. |
+| `kind: layout` | Install `templates/` plus any existing `images/` and `icons/` into the matching project roots; ignore `exports/`. Strategist locks structure; identity is decided in confirmation fields e–g. |
+| `kind: deck` | Install `templates/` plus any existing `images/` and `icons/` into the matching project roots; ignore `exports/`. Strategist locks all segments; confirmation narrows to deck-content fields. |
Normalize every explicit path before any write:
| Input shape | Spec / SVG source | Asset source | Install rule |
|---|---|---|---|
-| Current Layout/Deck workspace: `<root>/templates/design_spec.md` | `<root>/templates/` | `<root>/images/`, `<root>/icons/` | Map those three roots to the target project's matching roots; ignore `<root>/exports/` |
-| Direct Brand package: `<root>/design_spec.md`, `kind: brand` | `<root>/` | Package-local files | Spec/non-bitmap assets → project `templates/`; bitmaps → project `images/` |
-| Compatible legacy-flat Layout/Deck: `<root>/design_spec.md` | `<root>/` | Package-local files | Preserve the existing flat-package routing: SVG/spec/non-bitmaps → project `templates/`; bitmaps → project `images/`; route declared icons to project `icons/` |
+| Current workspace: `<root>/templates/design_spec.md` | `<root>/templates/` | Any existing `<root>/images/`, `<root>/icons/` | Map the existing portable roots to the target project's matching roots; ignore `<root>/exports/` |
+| Compatible legacy-flat package: `<root>/design_spec.md` | `<root>/` | Package-local files | SVG/spec/non-bitmaps → project `templates/`; bitmaps → project `images/`; route declared icons to project `icons/` |
**Atomic install preflight (mandatory)**: Resolve source and destination paths, enumerate the complete file mapping, and reject every destination collision before copying any file. Equality between a current project workspace root and the target project root means in-place consumption and no copy. For an external single path, a collision stops Step 3 rather than overwriting. For multi-path fusion, do not copy packages sequentially: resolve segment conflicts and asset-name conflicts first, construct one final mapping, then write it once. Never use recursive copy as an implicit conflict policy.
Never infer that a flat directory has legacy Master/Layout semantics solely from packaging.
-The same current-workspace split applies to layout and deck: source/spec in `templates/`, bitmaps in `images/`, runtime vectors in `icons/`, review artifacts in `exports/`. The spec's `kind` tells Strategist how to read the installed source. Template SVGs are not export-time overlays: visible output still lives completely in `svg_output/`. Their complete visuals and explicit Master/Layout/placeholder metadata are nevertheless the authoring prototypes selected by `page_layouts`.
+The same current-workspace routing applies to all three kinds: source/spec in `templates/`, visual assets in `images/`, runtime icons in `icons/`, and review artifacts in `exports/`. Empty optional roots are omitted rather than retained with placeholder files. Brand workspaces normally have no `exports/` because they have no SVG roster. The spec's `kind` tells Strategist how to read the installed source. Template SVGs are not export-time overlays: visible output still lives completely in `svg_output/`. Their complete visuals and explicit Master/Layout/placeholder metadata are nevertheless the authoring prototypes selected by `page_layouts`.
When `create-template` used project output scope, its workspace root is the target project itself and all core directories are already final. Resolve both roots before copying: equality means **in-place consumption**, so skip the installation. An in-place workspace cannot participate in multi-path fusion; use external workspaces for fusion. Never place the local source under a nested `templates/local_master/` directory because the confirmation and quality gates read the project `templates/` root.
-A project-scoped workspace has the same portable core structure as a library workspace. It may be copied or promoted across roots as one unit (`templates/`, `images/`, `icons/`); `exports/` stays review-only. Do not pass only another project's `templates/` subdirectory because that would omit sibling assets.
+A project-scoped workspace has the same portable routing as a library workspace. It may be copied or promoted across roots as one unit (`templates/` plus any existing `images/` and `icons/`); `exports/` stays review-only. Do not pass only another project's `templates/` subdirectory because that would omit sibling assets.
Legacy template packages may ship `native_structure.json` + `source_template.pptx`, omit root Master identity, use direct atomic placeholders, or carry old baseline/distillation metadata. Do not copy or consume those semantic contracts through Step 3. Run [`restore-pptx-structure`](workflows/restore-pptx-structure.md) on the package first, then return with the migrated workspace path. Old flat packaging remains readable when its SVG structure is already current.
diff --git a/skills/ppt-master/templates/brands/README.md b/skills/ppt-master/templates/brands/README.md
index fc2acc4d..bdb37f28 100644
--- a/skills/ppt-master/templates/brands/README.md
+++ b/skills/ppt-master/templates/brands/README.md
@@ -6,11 +6,11 @@ Brand is one of three template kinds in the library — alongside [`layouts/`](.
## How brands are consumed
-Brand application follows the **same explicit-path rule as all template kinds** at SKILL.md Step 3, and lands in the **same project directory** (`<project_path>/templates/`):
+Brand application follows the **same explicit-path rule and workspace routing as all template kinds** at SKILL.md Step 3:
| User input at SKILL.md Step 3 | Behavior |
|---|---|
-| An explicit brand directory path (e.g. `templates/brands/anthropic/`) | Copy `design_spec.md` + logo files + asset subdirectories into `<project_path>/templates/`; Strategist locks identity segment |
+| An explicit brand workspace path (e.g. `templates/brands/anthropic/`) | Resolve `templates/design_spec.md`; stage `templates/`, `images/`, and `icons/` into the matching project directories; Strategist locks the identity segment |
| Bare brand name only ("use anthropic brand"), brand mention without path, or silence | Skip — same mechanical rule as all template kinds: bare names never trigger |
| Brand path + layout path | Fuse into one `design_spec.md` — brand owns identity segment (color / typography / logo / voice / icon style); layout owns structure segment (canvas / page roster). See `SKILL.md` Step 3. |
| Brand path + deck path | Fuse — brand identity overrides deck identity; structure + middle segments come from deck |
@@ -29,25 +29,24 @@ Read skills/ppt-master/workflows/create-brand.md
Three input paths are supported: brand asset (logo / brand site URL / branded PPTX / brand PDF), verbal spec dictated in chat, or empty skeleton for the user to fill in later.
-## Package structure
+## Workspace structure
-Every brand directory is self-contained:
+Every brand uses the same workspace routing as layout and deck templates. Brand identity remains roster-free; omit empty optional directories instead of adding placeholder files.
```
templates/brands/<brand_id>/
-├── design_spec.md # required — brand identity spec (7 sections)
-├── logo.<ext> # optional — primary brand logo (single-lockup brands)
-│ …or…
-├── <brand>_wordmark.<ext> # optional — wordmark variant (dual-lockup brands)
-├── <brand>_mark.<ext> # optional — symbol / icon variant (dual-lockup brands)
-├── images/ # optional — branded photos
-├── illustrations/ # optional — branded illustrations
-└── icons/ # optional — branded icon overrides
+├── templates/
+│ └── design_spec.md # required — brand identity spec
+├── images/ # optional — logos and visual assets
+│ ├── logo.<ext> # optional — primary logo
+│ └── <brand>_wordmark.svg # optional — alternate lockups and visual assets
+├── icons/ # optional — branded icon overrides
+└── exports/ # optional local derived artifacts; Git-ignored
```
-Logo filenames are descriptive, not contractual — `design_spec.md` §IV lists the exact files and the contexts in which each is used. Single-lockup brands typically ship one `logo.<ext>`; dual-lockup brands (e.g. Google's wordmark + G mark) ship separately named files.
+Logo filenames are descriptive, not contractual — `templates/design_spec.md` §IV lists exact `../images/...` paths and usage contexts. Single-lockup brands typically ship one logo; dual-lockup brands ship separately named files.
-`design_spec.md` carries a YAML frontmatter block with `kind: brand` and is the single source of truth for the brand identity. The six required sections are: I Brand Overview / II Color Scheme / III Typography / IV Logo / V Voice & Tone / VI Icon Style.
+`templates/design_spec.md` carries a YAML frontmatter block with `kind: brand` and is the single source of truth for the brand identity. The six required sections are: I Brand Overview / II Color Scheme / III Typography / IV Logo / V Voice & Tone / VI Icon Style.
## Discovery index
diff --git a/skills/ppt-master/workflows/create-brand.md b/skills/ppt-master/workflows/create-brand.md
index 8d86b90c..7e92864d 100644
--- a/skills/ppt-master/workflows/create-brand.md
+++ b/skills/ppt-master/workflows/create-brand.md
@@ -1,10 +1,10 @@
---
-description: Generate a brand-only template under `templates/brands/<id>/` — a design_spec.md that captures the user's colors / typography / logo / voice / icon style without an SVG page roster, so subsequent PPT projects inherit brand identity while keeping page layout free.
+description: Generate a brand-only workspace under `templates/brands/<id>/` that captures colors, typography, logos, voice, and icon style without an SVG page roster.
---
# Create Brand Workflow
-> Standalone preset-creation workflow. Output is a brand template package at `skills/ppt-master/templates/brands/<brand_id>/`. Structurally a brand is a template minus the SVG page roster — Strategist locks the brand's color / typography / logo / voice as truth; Executor designs pages freely under those constraints.
+> Standalone preset-creation workflow. Output is a complete brand workspace at `skills/ppt-master/templates/brands/<brand_id>/`. A brand keeps the common workspace shape but omits the SVG page roster: Strategist locks identity while Executor designs pages freely.
This workflow edits the global brand library, not any specific `projects/<x>/`. Consumption follows the same explicit-path rule as layout templates (see [Downstream consumption](#downstream-consumption-informational) at the end).
@@ -14,7 +14,7 @@ This workflow edits the global brand library, not any specific `projects/<x>/`.
| User signal | Action |
|---|---|
-| "set up brand" / "extract brand from this logo" / 建立品牌 / 做品牌规范 | Run this workflow |
+| "set up brand" / "extract brand from this logo" | Run this workflow |
| User provides a brand asset (logo / brand site URL / branded PPTX / brand PDF) and wants it locked across future projects | Run this workflow |
| User mentions brand color or font once for a single deck only | Skip — handle inline via Strategist h.5 |
| `templates/brands/<requested_id>/` already exists | Ask: update / replace / use a new id — never silently overwrite |
@@ -66,7 +66,7 @@ Whatever the user gives is `[user]`-labelled. Skip Step 3 unless the user explic
## Step 2C: Empty skeleton
-Write `templates/brands/<brand_id>/design_spec.md` with the full schema, every value as a TODO comment. Tell the user where the file is. No further prompting — the user owns it from here.
+Write `templates/brands/<brand_id>/templates/design_spec.md` with the full schema, every value as a TODO comment. Tell the user where the file is. No further prompting — the user owns it from here.
---
@@ -85,15 +85,15 @@ For fields not covered by the asset, ask the user in a single bundled message. S
---
-## Step 4: Materialize the brand package
+## Step 4: Materialize the brand workspace
-Create the package directory:
+Create the required template source directory. Create `images/`, `icons/`, or `exports/` only when writing a real asset or derived artifact; never add placeholder files for empty directories.
```bash
-mkdir -p "skills/ppt-master/templates/brands/<brand_id>"
+mkdir -p "skills/ppt-master/templates/brands/<brand_id>/templates"
```
-### Mandatory: `design_spec.md`
+### Mandatory: `templates/design_spec.md`
```markdown
---
@@ -132,7 +132,7 @@ primary_color: "#XXXXXX"
| mono | <family> | optional |
## IV. Logo
-- File: `./logo.<ext>` (relative to this design_spec.md)
+- File: `../images/logo.<ext>` (relative to this design_spec.md)
- Usage: cover-only \| every-page \| never
## V. Voice & Tone
@@ -145,28 +145,27 @@ primary_color: "#XXXXXX"
- Preference: linear \| filled \| duotone # optional, drives icon library search
## VII. Visual Assets (optional)
-- Images: `./images/` # branded photos, prioritised before AI image generation
-- Illustrations: `./illustrations/` # branded illustrations, prioritised before AI generation
-- Icons: `./icons/` # branded icon overrides; falls back to `templates/icons/`
+- Images and illustrations: `../images/` # brand visual assets
+- Icons: `../icons/` # branded icon overrides
```
**Section scope rules**:
-- Layout / canvas / spacing / radius / shadow / page roster / signature design elements are OUT of brand scope. Those live in layout / deck templates (`templates/layouts/<id>/design_spec.md` or `templates/decks/<id>/design_spec.md`) or `shared-standards.md`. Do NOT add those sections here.
+- Layout / canvas / spacing / radius / shadow / page roster / signature design elements are OUT of brand scope. Those live in layout / deck workspaces (`templates/layouts/<id>/templates/design_spec.md` or `templates/decks/<id>/templates/design_spec.md`) or `shared-standards.md`. Do NOT add those sections here.
- HEX must be `#RRGGBB`
- Font names are free strings; not validated against locally installed fonts
- §VII is fully optional — list only directories that actually exist
### Optional: logo file
-If the user provided a logo, copy it to `templates/brands/<brand_id>/logo.<ext>` (preserve source extension).
+If the user provided a logo, copy it to `templates/brands/<brand_id>/images/logo.<ext>` and preserve its source extension. Use descriptive filenames when several lockups exist.
### Optional: visual asset directories
-If the user provided brand photo / illustration / icon folders, copy them as `images/` / `illustrations/` / `icons/` under `templates/brands/<brand_id>/`. Reference each in §VII of `design_spec.md`. Skip the entire section if none exist.
+Copy brand photos and illustrations into the workspace `images/` directory. Copy branded icon overrides into `icons/`. Reference only directories and assets that actually exist in §VII of `templates/design_spec.md`.
### NOT created here
-No SVG page roster. No canvas spec. No signature design elements. If the user later wants brand-anchored page templates, run `create-template.md` with this brand as a style reference.
+No SVG page roster, canvas spec, signature design elements, or preview PPTX. Do not create an empty `exports/` directory. If the user later wants brand-anchored page templates, run `create-template.md` with this brand as a style reference.
---
@@ -189,16 +188,16 @@ Emit the confirmation card:
```markdown
## ✅ Brand Saved
- Path: `skills/ppt-master/templates/brands/<brand_id>/`
-- Files: design_spec.md{, logo.<ext>}{, images/}{, illustrations/}{, icons/}
+- Files: templates/design_spec.md{, images/logo.<ext>}{, images/*}{, icons/*}
- Fields locked: <list>
- Provenance: <fact / approx / user counts>
How to use in a project:
-- Include the brand directory path in your initial Step 3 input — e.g. "做一个 Q4 总结 PPT, 用 skills/ppt-master/templates/brands/<brand_id>/ 这个品牌"
+- Include the brand workspace path in the initial Step 3 input, for example: "Create a Q4 summary using skills/ppt-master/templates/brands/<brand_id>/"
- Same explicit-path rule as layout templates: bare brand names never trigger
- May be supplied together with a layout template path; Step 3 fuses both into a single `design_spec.md` (brand wins on identity tokens, layout wins on page structure) — see `SKILL.md` Step 3
- To list available brands: open `templates/brands/brands_index.json`
-- To edit: modify `templates/brands/<brand_id>/design_spec.md` directly, then re-run `python3 skills/ppt-master/scripts/register_template.py --kind brand <brand_id>`
+- To edit: modify `templates/brands/<brand_id>/templates/design_spec.md`, then re-run `python3 skills/ppt-master/scripts/register_template.py --kind brand <brand_id>`
```
---
@@ -209,7 +208,7 @@ Brand application happens in [`SKILL.md` Step 3](../SKILL.md) under the **same e
| User input at SKILL.md Step 3 | Behavior |
|---|---|
-| Explicit brand directory path supplied | Step 3 copies the brand into `<project_path>/templates/` (same target as a layout template); Strategist locks color / typography / logo / voice as truth at Step 4 |
+| Explicit brand workspace path supplied | Step 3 resolves `templates/design_spec.md`, stages `templates/`, `images/`, and `icons/` into their project peers, and locks color / typography / logo / voice as truth at Step 4 |
| Bare brand name, brand mention without path, or silence | Skip — no auto-application based on directory count or any other implicit signal |
| Both a brand path and a layout template path supplied in the same message | Step 3 fuses both into a single `design_spec.md` inside `<project_path>/templates/` (brand wins on identity tokens, layout wins on page structure). See `SKILL.md` Step 3 for the field-precedence table and the two conflict gates that may surface a clarifying question |
@@ -220,7 +219,7 @@ Brand application happens in [`SKILL.md` Step 3](../SKILL.md) under the **same e
## Notes
1. **Brand is identity, not layout** — colors / typography / logo / voice / icon style only. Page roster, canvas spec, and signature design elements belong to layout templates; do not duplicate them here.
-2. **Self-contained package** — all brand assets (logo, images, illustrations, icons) live inside `templates/brands/<brand_id>/`. Nothing leaks to workspace root or `projects/`.
+2. **Common workspace routing** — brand assets use the same `templates/`, `images/`, `icons/`, and `exports/` routes as other template kinds; empty optional directories are omitted.
3. **No script dependency** — Step 2A reuses existing converters plus AI inline reading. A dedicated `brand_extract.py` is not introduced unless future user feedback demands batch processing or precise color picking from raster logos.
4. **Multi-brand support** — `templates/brands/` accepts any number of brands; agency / freelancer / multi-client workflows are natural.
5. **Precedence rule** — when a brand and a layout template both apply, Step 3 fuses them into one `design_spec.md`: brand wins on color / typography / logo / voice / icon style; layout wins on canvas / page roster / spacing / font-size hierarchy / signature visual elements. See `SKILL.md` Step 3 for the full precedence table.