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

fix(skill): keep the package self-contained

hugohe3c00b8ff76c25
diff --git a/skills/ppt-master/.env.example b/skills/ppt-master/.env.example
index a463323a..6bcd1f81 100644
--- a/skills/ppt-master/.env.example
+++ b/skills/ppt-master/.env.example
@@ -170,12 +170,12 @@
# Use cloud providers only when you want high-quality or cloned voices —
# all four (ElevenLabs / MiniMax / Qwen / CosyVoice) accept a cloned voice_id.
# Clone the voice in the provider's console first, then pass --voice-id to
-# notes_to_audio.py. See docs/audio-narration.md "Use a cloned voice".
+# notes_to_audio.py. See workflows/stages/generate-audio.md.
# edge-tts 是默认旁白后端,无需 API Key。
# 需要高质量云端旁白或复刻音色时再配置云端提供商——
# ElevenLabs / MiniMax / Qwen / CosyVoice 四家都支持传入复刻 voice_id。
# 先在 provider 控制台复刻得到 voice_id,再用 --voice-id 传给 notes_to_audio.py。
-# 详见 docs/zh/audio-narration.md "使用复刻音色"。
+# 详见 workflows/stages/generate-audio.md。
#
# ELEVENLABS_API_KEY=your-elevenlabs-api-key
# MINIMAX_API_KEY=your-minimax-key
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 7236d163..74ef037c 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -55,6 +55,10 @@ description: >
> - `ppt-master` is a repository-specific workflow, not a general application scaffold
> - 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
+> - Keep this Skill package self-contained: required workflow, reference,
+> script, and template documentation MUST resolve inside this Skill directory;
+> repository-level documents may link into the package, but package files
+> MUST NOT depend on them
## Rule Strength Labels
@@ -277,7 +281,10 @@ There is no slug matching, no name lookup, no fuzzy resolution. A name without a
#### Three template kinds
-The architecture has three independent reference bundles. Full schema in [`docs/zh/templates-architecture.md`](../../docs/zh/templates-architecture.md). Summary:
+The architecture has three independent reference bundles. The shared package
+model and workspace contract live in [`templates/README.md`](templates/README.md);
+kind-specific schemas live in the corresponding template-directory README.
+Summary:
| Kind | Physical dir | Contains | Frontmatter |
|---|---|---|---|
@@ -954,4 +961,4 @@ Before switching roles, **MUST first read** the corresponding reference file. Ou
## Notes
- Local preview: `python3 -m http.server -d <project_path>/svg_final 8000`
-- **Troubleshooting**: on generation issues (layout overflow, export errors, blank images, etc.), check `docs/faq.md` for known solutions
+- **Troubleshooting**: on generation issues (layout overflow, export errors, blank images, etc.), check [`scripts/docs/troubleshooting.md`](scripts/docs/troubleshooting.md)
diff --git a/skills/ppt-master/references/ai-image-comparison/README.md b/skills/ppt-master/references/ai-image-comparison/README.md
index 4a00ce21..96706d83 100644
--- a/skills/ppt-master/references/ai-image-comparison/README.md
+++ b/skills/ppt-master/references/ai-image-comparison/README.md
@@ -3,7 +3,7 @@
PPT Master's AI images are governed by three orthogonal dimensions: **rendering (visual style) × palette (color behavior) × type (internal composition)**.
This directory uses **controlled-variable comparison** — vary one dimension while holding the other two fixed — so you can see exactly what each dimension contributes.
-> This is **not** an example project (see `examples/` for those). It is a dimension-selection reference for the Strategist role and end users when picking AI image parameters.
+> This is **not** an example project. It is a dimension-selection reference for the Strategist role and end users when picking AI image parameters.
## The three comparison sets
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 4d6aae08..9cade6df 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -346,7 +346,7 @@ grep "chart-plot-area" <project_path>/svg_output/<current_page>.svg
> the same library do not use a plot-area marker.
- **Technical specs**: see [shared-standards.md](shared-standards.md) for SVG/PPT constraints
- **Card containers — use the documented patterns**: when a content page needs section cards (4 quadrants, parallel aspects, capability blocks, info cards), use the patterns codified in [`templates/charts/CHART_STYLE_GUIDE.md`](../templates/charts/CHART_STYLE_GUIDE.md) §11 — half-rounded section tab (§11.1), nested card border without stroke (§11.2), card-grid skeletons (§11.3), diagonal dashed relationship arrow for cross-quadrant relationships (§11.5), ground-anchor ellipse as a non-filter depth marker (§11.6), bidirectional interaction arrows for paired protocols (§11.7). Do not reinvent the "tinted full-rounded rect + white cover-rect to hide the bottom corners" hack; it survives in older templates but breaks SVG→PPTX color editing. Reference templates: [`labeled_card.svg`](../templates/charts/labeled_card.svg), [`quadrant_text_bullets.svg`](../templates/charts/quadrant_text_bullets.svg), [`kpi_cards.svg`](../templates/charts/kpi_cards.svg), [`matrix_2x2.svg`](../templates/charts/matrix_2x2.svg), [`team_roster.svg`](../templates/charts/team_roster.svg), [`client_server_flow.svg`](../templates/charts/client_server_flow.svg).
-- **Reference — prefer semantic shapes over preset stacks (not a constraint)**: when a slide needs to express "ascending / converging / breaking through / stacking" — i.e., a relationship that goes beyond a generic arrow — prefer a single custom `<polygon>` or `<path>` that encodes the semantics geometrically, rather than stacking multiple preset arrows. A converging-tip path or a podium polygon reads faster than three arrows pointing at a label. Examples of this technique appear in many imported corporate decks; see `projects/01_template_import/svg_output/slide_01.svg` shape-158 for a reference (gradient-filled inward-pointing arrow). Do not codify these as templates — they are page-specific; the rule is just "consider polygon before stacking presets."
+- **Reference — prefer semantic shapes over preset stacks (not a constraint)**: when a slide needs to express "ascending / converging / breaking through / stacking" — i.e., a relationship that goes beyond a generic arrow — prefer a single custom `<polygon>` or `<path>` that encodes the semantics geometrically, rather than stacking multiple preset arrows. A converging-tip path or a podium polygon reads faster than three arrows pointing at a label. Do not codify these as templates — they are page-specific; the rule is just "consider polygon before stacking presets."
- **Reference — visual depth through restraint (not a constraint)**: layered depth comes from rhythm (flat vs lifted, dense vs spacious), not from shadows everywhere. Shadow typically suits 2-3 genuinely floating elements per page (cards on photos, primary CTA, overlays); keep peer-grid cards, dividers, body containers flat. Reach for typography weight, spacing, accent bars, subtle tints **before** shadow.
### 3.2 PowerPoint-Native Chart/Table Replacement Marker (MANDATORY on eligible data-chart and text-grid table pages)
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 02e4e7f8..2bc4412e 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -182,7 +182,7 @@ dropped.
PPTX import compatibility, tolerant recovery, strict-mode rejection, and
diagnostic behavior are indexed in
-[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §11.
+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).
---
@@ -720,7 +720,7 @@ PPTX import is a user-input boundary, not generated authoring. Tolerant mode
retains recognized color semantics, omits only unsupported paint properties,
and records the decision in `conversion-report.json`; `--strict` keeps the
closed parser checks. See
-[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §11.
+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).
---
### 6.3 Gradients and Paint Effects
@@ -747,7 +747,7 @@ retain only the first stop. Stop alpha and element opacity multiply.
PPTX import normalizes compatible gradients and records any property-level
degradation without aborting the deck; `--strict` keeps the closed parser
contract. See
-[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §11.
+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).
The quality checker and exporter preflight both validate definition location,
references, gradient structure, and paint context from the same closed contract.
@@ -806,8 +806,8 @@ PowerPoint object; this exception does not authorize filters on ordinary groups.
PPTX import preserves one registered shape/connector shadow or glow and records
unsupported object/run effects as import diagnostics instead of exposing a new
authoring surface. See
-[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §11 for
-tolerant, strict, and release-handling behavior.
+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary)
+for tolerant, strict, and release-handling behavior.
The quality checker and exporter preflight enforce the same definition,
reference, primitive, target, and numeric-value contract. Missing required
geometry and malformed values are never replaced by effect defaults during
@@ -965,7 +965,7 @@ fidelity.
PPTX import treats unsupported line properties as source diagnostics: tolerant
mode retains the object and omits only the unsupported outline; `--strict`
retains the closed rejection behavior. See
-[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §11.
+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).
The dash grammar is closed: exact lowercase `none`, or at least two finite
unitless numbers separated by whitespace or one comma. Generated SVG uses
@@ -1342,7 +1342,7 @@ grain and explicit circles/paths only for sparse editable marks.
Unsupported source effects remain visible where possible and retain their
import diagnostics. Resolve those diagnostics before release export; see
-[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §11.
+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).
---
@@ -1447,8 +1447,7 @@ type, chart data shape, and any imported fallback baseline before export.
Imported marker freshness, fallback classification, provenance, and legacy
read compatibility are operational import concerns. Keep generated authoring
free of those attributes; use the exact behavior and field index in
-[`conversion.md`](../scripts/docs/conversion.md#pptx_to_svgpy) and
-[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §7/§11.
+[`conversion.md`](../scripts/docs/conversion.md#native-table-and-chart-import-claims).
```xml
<g id="p03-revenue-chart" data-pptx-replace-with="chart">
@@ -1763,8 +1762,7 @@ the two optional canonical booleans below so export can write the preserved sour
package fields without inferring visibility from which shapes happen to be
present. Authored `standard` / `fidelity` templates normally omit both and use
the default `true`. See
-[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §2 and
-[`conversion.md`](../scripts/docs/conversion.md#pptx_to_svgpy).
+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).
**Master text-style contract**: Flat and structured export map the
locked `title` size to every `a:defRPr` in Master `p:titleStyle`. Level 1 in
diff --git a/skills/ppt-master/scripts/batch_validate.py b/skills/ppt-master/scripts/batch_validate.py
index 9686ed1d..29aaeb36 100644
--- a/skills/ppt-master/scripts/batch_validate.py
+++ b/skills/ppt-master/scripts/batch_validate.py
@@ -200,7 +200,7 @@ class BatchValidator:
if self.summary['missing_readme'] > 0:
print(f" 1. Create documentation for projects missing README")
print(
- f" Reference: examples/google_annual_report_ppt169_20251116/README.md")
+ f" Include the project goal, sources, canvas, artifacts, and export path")
if self.summary['svg_issues'] > 0:
print(f" 2. Check SVG root viewBox settings")
diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.md
index 66b3e1ec..e8e683e1 100644
--- a/skills/ppt-master/scripts/docs/conversion.md
+++ b/skills/ppt-master/scripts/docs/conversion.md
@@ -1,6 +1,9 @@
# Conversion Tools
-> Architecture rationale (why native-Python first with pandoc fallback, why curl_cffi for TLS impersonation): see [docs/technical-design.md "Source Content Conversion"](../../../../docs/technical-design.md#source-content-conversion).
+> **Design boundary**: use native-Python converters for supported formats,
+> invoke Pandoc only for explicit fallback formats, and let web conversion use
+> `curl_cffi` when available for sites that reject Python's default TLS
+> fingerprint.
Source conversion tools turn PDFs, documents, slide decks, and web pages into Markdown before project creation.
@@ -255,6 +258,8 @@ relationship preference for asset identity; its existing missing-media gate
remains strict rather than silently treating the raster preview as the
template's canonical asset.
+### Import compatibility and recovery boundary
+
Import is tolerant by default because the source deck is user-owned or comes
from third-party authoring tools. Recovery happens at the narrowest safe
boundary: first omit only an unsupported property or feature; if that is not
@@ -276,6 +281,8 @@ the native replacement claim or strict mode. Default tolerant deck import
retains the usable fallback/object and records the degradation; it does not
discard unrelated shapes, pages, or the entire deck.
+### Native table and chart import claims
+
Supported text-grid tables and conservative classic-chart caches carry a
`data-pptx-replace-with` claim beside their SVG fallback, with the replacement
payload in a child `<metadata type="application/json">`. The parent claim
@@ -390,21 +397,39 @@ literal field fallback because one shared part can serve multiple slides.
### Maintenance smoke checks
Run these checks from the repository root after changing `pptx_to_svg/` or its
-CLI. They use a shipped deck and generated adversarial input; do not replace
-them with a committed `test_*.py` suite.
+CLI. They generate every required input under `/tmp`; do not replace them with
+a committed `test_*.py` suite.
#### Healthy generated deck
```bash
+python3 - <<'PY'
+from pptx import Presentation
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.util import Inches
+
+presentation = Presentation()
+slide = presentation.slides.add_slide(presentation.slide_layouts[6])
+shape = slide.shapes.add_shape(
+ MSO_SHAPE.RECTANGLE,
+ Inches(1),
+ Inches(1),
+ Inches(3),
+ Inches(1),
+)
+shape.text = "PPTX import smoke check"
+presentation.save("/tmp/ppt-master-smoke-healthy.pptx")
+PY
+
python3 "skills/ppt-master/scripts/pptx_to_svg.py" \
- "examples/ppt169_kubernetes_blueprint_2026/exports/kubernetes_blueprint_2026.pptx" \
+ "/tmp/ppt-master-smoke-healthy.pptx" \
--inheritance-mode flat \
- -o "/tmp/ppt-master-smoke-kubernetes"
-python3 -c "import json; from pathlib import Path; report = json.loads(Path('/tmp/ppt-master-smoke-kubernetes/conversion-report.json').read_text()); assert report['summary'] == {'slides': 10, 'warnings': 0}, report['summary']; print('OK: 10 slides, 0 warnings')"
+ -o "/tmp/ppt-master-smoke-healthy"
+python3 -c "import json; from pathlib import Path; report = json.loads(Path('/tmp/ppt-master-smoke-healthy/conversion-report.json').read_text()); assert report['summary'] == {'slides': 1, 'warnings': 0}, report['summary']; print('OK: 1 slide, 0 warnings')"
```
Expected: both commands exit `0`; the assertion prints
-`OK: 10 slides, 0 warnings`.
+`OK: 1 slide, 0 warnings`.
#### Tolerant/strict color-structure probe
diff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.md
index f8824977..127b6d9d 100644
--- a/skills/ppt-master/scripts/docs/image.md
+++ b/skills/ppt-master/scripts/docs/image.md
@@ -1,6 +1,9 @@
# Image Tools
-> Architecture rationale (why provider-specific config keys instead of a generic `IMAGE_API_KEY`, why permissive license filter with strict-mode escape hatch, why external refs in dev but two divergent embedding strategies for delivery): see [docs/technical-design.md "Image Acquisition & Embedding"](../../../../docs/technical-design.md#image-acquisition--embedding).
+> **Design boundary**: keep provider credentials explicit, keep in-pipeline
+> acquisition manifest-driven, and treat external image references as authoring
+> inputs while delivery writes self-contained SVG previews and native PPTX
+> media.
Image tools cover formula rendering, prompt-based AI generation, web image search, image inspection, and Gemini watermark removal.
diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.md
index 607b15ec..4c9badec 100644
--- a/skills/ppt-master/scripts/docs/project.md
+++ b/skills/ppt-master/scripts/docs/project.md
@@ -1,6 +1,8 @@
# Project Tools
-> Architecture rationale (why `import-sources` defaults are asymmetric for in-repo vs out-of-repo files): see [docs/technical-design.md "Project Structure & Lifecycle"](../../../../docs/technical-design.md#project-structure--lifecycle).
+> **Import boundary**: copy out-of-repository sources by default to protect user
+> files; move in-repository sources by default to avoid leaving accidental
+> commit artifacts. Explicit `--copy` / `--move` flags override the default.
Project tools create, validate, and inspect the standard PPT Master workspace.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 8393f94d..02f596f3 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -1,6 +1,8 @@
# SVG Pipeline Tools
-> Architecture rationale (why each artifact / step exists, deletion impact, two-consumer relationship between `svg_finalize/` and native pptx conversion): see [docs/technical-design.md "Post-Processing Pipeline"](../../../../docs/technical-design.md#post-processing-pipeline).
+> **Maintenance boundary**: post-processing modules serve both the on-disk
+> `svg_final/` preview and in-memory native PPTX conversion. Check both
+> consumers before changing or removing a step.
These tools cover post-processing, SVG validation, speaker notes, recorded narration, and PPTX export.
diff --git a/skills/ppt-master/scripts/docs/update_spec.md b/skills/ppt-master/scripts/docs/update_spec.md
index 93731f9a..f88ac29c 100644
--- a/skills/ppt-master/scripts/docs/update_spec.md
+++ b/skills/ppt-master/scripts/docs/update_spec.md
@@ -1,6 +1,8 @@
# update_spec.py
-> Architecture rationale (why narrow scope, why no backups, the spec_lock as execution contract): see [docs/technical-design.md "Spec Propagation"](../../../../docs/technical-design.md#spec-propagation-spec_lockmd-as-execution-contract).
+> **Scope boundary**: this tool updates only deterministic global color and font
+> substitutions, writes the authoritative `spec_lock.md` first, and relies on
+> version control for rollback instead of creating parallel backups.
Propagate a `spec_lock.md` value change to both the lock file and every `svg_output/*.svg`. The single edit surface for bulk style tweaks after generation.
diff --git a/skills/ppt-master/scripts/error_helper.py b/skills/ppt-master/scripts/error_helper.py
index 6446e2f6..68b8f262 100644
--- a/skills/ppt-master/scripts/error_helper.py
+++ b/skills/ppt-master/scripts/error_helper.py
@@ -22,8 +22,8 @@ class ErrorHelper:
'message': 'Missing README.md file',
'solutions': [
'Create a README.md file with project description, usage instructions, etc.',
- 'Reference template: examples/google_annual_report_ppt169_20251116/README.md',
- 'Or use command: cp examples/google_annual_report_ppt169_20251116/README.md <your_project>/'
+ 'Document the project goal, source material, canvas, generated artifacts, and export path',
+ 'Keep project-specific instructions local instead of copying a repository example'
],
'severity': 'error'
},
diff --git a/skills/ppt-master/scripts/finalize_svg.py b/skills/ppt-master/scripts/finalize_svg.py
index 05781a47..9e3fd38d 100644
--- a/skills/ppt-master/scripts/finalize_svg.py
+++ b/skills/ppt-master/scripts/finalize_svg.py
@@ -13,7 +13,7 @@ Architecture note: this module's outputs feed svg_final/ on disk AND its
sub-modules (svg_finalize.embed_icons, svg_finalize.flatten_tspan, ...)
are memory-reused by svg_to_pptx during native conversion. Deleting any
step here may also break native pptx output, not just svg_final/.
-See docs/technical-design.md "Post-Processing Pipeline" before modifying.
+See scripts/docs/svg-pipeline.md before modifying the shared pipeline.
Usage:
# Execute all processing steps (recommended)
diff --git a/skills/ppt-master/scripts/generate_examples_index.py b/skills/ppt-master/scripts/generate_examples_index.py
index 0ac28d25..388421d4 100644
--- a/skills/ppt-master/scripts/generate_examples_index.py
+++ b/skills/ppt-master/scripts/generate_examples_index.py
@@ -9,10 +9,11 @@ Usage:
python3 scripts/generate_examples_index.py examples
"""
+import os
import sys
-from pathlib import Path
-from datetime import datetime
from collections import defaultdict
+from datetime import datetime
+from pathlib import Path
from console_encoding import configure_utf8_stdio
@@ -37,11 +38,18 @@ def generate_examples_index(examples_dir: str = 'examples') -> str:
Generated README.md content
"""
examples_path = Path(examples_dir)
+ skill_dir = Path(__file__).resolve().parent.parent
if not examples_path.exists():
print(f"[ERROR] Directory not found: {examples_dir}")
return ""
+ def skill_link(target: Path) -> str:
+ """Return a link from the generated index to a packaged Skill resource."""
+ return Path(
+ os.path.relpath(target, start=examples_path.resolve())
+ ).as_posix()
+
print(f"[SCAN] Scanning directory: {examples_dir}")
# Find all projects
@@ -70,7 +78,7 @@ def generate_examples_index(examples_dir: str = 'examples') -> str:
# Generate README content
content = []
content.append("# PPT Master Example Projects Index\n")
- content.append("> This file is auto-generated by `skills/ppt-master/scripts/generate_examples_index.py`\n")
+ content.append("> This file is auto-generated by the packaged `scripts/generate_examples_index.py`\n")
content.append(f"> Last updated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
# Overview statistics
@@ -190,11 +198,13 @@ def generate_examples_index(examples_dir: str = 'examples') -> str:
# Related resources
content.append("## [Resources] Related Resources\n")
- content.append("- [Quick Start](../README.md)")
- content.append("- [Workflow Tutorial](../../AGENTS.md)")
- content.append("- [Canvas Formats](../references/canvas-formats.md)")
- content.append("- [Role Definitions](../references/)")
- content.append("- [Chart Templates](../templates/charts/README.md)\n")
+ content.append(f"- [Workflow]({skill_link(skill_dir / 'SKILL.md')})")
+ content.append(
+ f"- [Canvas Formats]({skill_link(skill_dir / 'references' / 'canvas-formats.md')})")
+ content.append(
+ f"- [Role Definitions]({skill_link(skill_dir / 'references')})")
+ content.append(
+ f"- [Chart Templates]({skill_link(skill_dir / 'templates' / 'charts' / 'README.md')})\n")
# Footer
content.append("---\n")
diff --git a/skills/ppt-master/scripts/register_template.py b/skills/ppt-master/scripts/register_template.py
index 5f9c6b77..a270b1cf 100644
--- a/skills/ppt-master/scripts/register_template.py
+++ b/skills/ppt-master/scripts/register_template.py
@@ -1,8 +1,8 @@
#!/usr/bin/env python3
"""Register a brand / layout / deck template into the global template index.
-Three kinds, three workspace roots, three index files (see
-``docs/zh/templates-architecture.md`` for the data model):
+Three kinds, three workspace roots, three index files. The shared model lives
+in ``templates/README.md``; each kind's schema lives in its directory README:
| --kind | Workspace roots | Index file |
|---------|-------------------------|-------------------------------|
diff --git a/skills/ppt-master/scripts/svg_finalize/__init__.py b/skills/ppt-master/scripts/svg_finalize/__init__.py
index 9acef8ee..4434081c 100644
--- a/skills/ppt-master/scripts/svg_finalize/__init__.py
+++ b/skills/ppt-master/scripts/svg_finalize/__init__.py
@@ -7,6 +7,6 @@ Used by two consumers:
in memory during native pptx conversion
Deleting any module here is likely to break native pptx output, not just
-svg_final/. See docs/technical-design.md "Post-Processing Pipeline" for
-the full per-module consumer table.
+svg_final/. See scripts/docs/svg-pipeline.md for the full per-module consumer
+table.
"""
diff --git a/skills/ppt-master/templates/brands/README.md b/skills/ppt-master/templates/brands/README.md
index 2308186e..9afb23ed 100644
--- a/skills/ppt-master/templates/brands/README.md
+++ b/skills/ppt-master/templates/brands/README.md
@@ -2,7 +2,10 @@
This directory holds **brand-only templates**: identity bundles (color / typography / logo / voice / icon style) without an SVG page roster. Strategist locks the brand's identity segment as truth; Executor designs pages freely under those constraints.
-Brand is one of three template kinds in the library — alongside [`layouts/`](../layouts/) (structure-only) and [`decks/`](../decks/) (complete identity + structure). Full data model: [`docs/zh/templates-architecture.md`](../../../../docs/zh/templates-architecture.md).
+Brand is one of three template kinds in the library — alongside
+[`layouts/`](../layouts/) (structure-only) and [`decks/`](../decks/) (complete
+identity + structure). The shared kind and workspace model lives in the
+parent [`README.md`](../README.md).
## How brands are consumed
diff --git a/skills/ppt-master/templates/decks/README.md b/skills/ppt-master/templates/decks/README.md
index 0e9524c4..29badfc0 100644
--- a/skills/ppt-master/templates/decks/README.md
+++ b/skills/ppt-master/templates/decks/README.md
@@ -14,9 +14,9 @@ mode decides whether the system is newly authored or materialized from validated
The discovery source of truth is [`decks_index.json`](./decks_index.json)
(`deck_id → { summary, canvas_format, page_count, primary_color }`). This README
-defines the kind and intentionally does not enumerate installed decks. See
-[`docs/zh/templates-architecture.md`](../../../../docs/zh/templates-architecture.md)
-for the complete data model.
+defines the kind and intentionally does not enumerate installed decks. The
+shared kind and workspace model lives in the parent
+[`README.md`](../README.md).
---
diff --git a/skills/ppt-master/templates/layouts/README.md b/skills/ppt-master/templates/layouts/README.md
index f00ec026..d42e1aba 100644
--- a/skills/ppt-master/templates/layouts/README.md
+++ b/skills/ppt-master/templates/layouts/README.md
@@ -19,9 +19,9 @@ projects repaint and retype the selected structure from the project lock.
The discovery source of truth is [`layouts_index.json`](./layouts_index.json)
(`layout_id → { summary, canvas_format, page_count, page_types }`). This README
-defines the kind and intentionally does not enumerate installed layouts. See
-[`docs/zh/templates-architecture.md`](../../../../docs/zh/templates-architecture.md)
-for the complete data model.
+defines the kind and intentionally does not enumerate installed layouts. The
+shared kind and workspace model lives in the parent
+[`README.md`](../README.md).
---
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index 0c20b50a..f756ada7 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -30,7 +30,9 @@ Create Template is the fixed user-facing entry and common contract. It selects o
Select Create Brand only for identity-only intent. Select Create Layout only when identity must remain downstream-selectable. Otherwise select Create Deck. Ask one discriminator question only when the user's requested reusable artifact is genuinely ambiguous; once selected, enter that child workflow and do not repeat route selection inside its confirmation gate.
-See [`docs/zh/templates-architecture.md`](../../../docs/zh/templates-architecture.md) for the kind/schema/fusion model.
+See [`templates/README.md`](../templates/README.md) for the shared kind and
+workspace model. Downstream template application and fusion remain owned by
+[`SKILL.md`](../SKILL.md) Step 3.
## Output scope — library (default) vs project
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
index b13e36a7..a5a3fe20 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -6,7 +6,9 @@ description: Deterministic selection among PPT Master's four top-level artifact
Route selection authority for PPT Master. Select exactly one top-level route, then activate only the child workflows, profiles, and stages owned by that route.
-**Hard rule**: If this file conflicts with a route summary in `SKILL.md`, `AGENTS.md`, or a user-facing document, this file wins for route selection. After selection, the route authority owns execution.
+**Hard rule**: If this file conflicts with a route summary elsewhere in the
+Skill package or in a repository-level user-facing document, this file wins for
+route selection. After selection, the route authority owns execution.
---