How to Register and Use a Custom Template in PPT Master: Complete Workflow Guide

Register a custom template in PPT Master by adding a validated JSON entry to templates/layouts/layouts_index.json and copying the template assets into your project's templates/ directory to bind the design specification to the generation pipeline.

The hugohe3/ppt-master repository separates template creation from presentation generation through a strict two-phase workflow. To register and utilize a custom template, you must first build a reusable layout package and index it in the global library, then manually instantiate those assets in your target project directory.

Understanding the PPT Master Template Architecture

PPT Master enforces a clear boundary between template creation and presentation generation. A custom layout only becomes available to the engine after it is registered in the global template library and subsequently copied into a specific project. This architecture ensures consistency across projects while allowing brand-specific customization.

The workflow relies on two core components:

• templates/layouts/layouts_index.json – The central registry that maps template IDs to metadata.
• design_spec.md – The project-level specification that drives SVG generation and layout decisions.

According to the source code in workflows/create-template.md, registration is Step 6 of the creation process, while utilization follows the "Template Option" branch documented in SKILL.md.

Phase 1: Creating and Registering Your Custom Template

Before utilizing a layout, you must construct a valid template package and register it in the global index. This phase involves asset preparation, validation, and JSON registration.

Step 1 – Build the Template Package

Create a dedicated directory for your template under templates/layouts/<template_id>/. Populate it with the core assets required by the executor:

• design_spec.md – The canonical design specification that defines typography, color palettes, and layout grids.
• Core SVGs – Template files such as 01_cover.svg, 02_section.svg, 03_content.svg, and 04_ending.svg that establish the visual structure.
• Optional reference assets – PNG/JPG files for backgrounds or logos.

To bootstrap from an existing PowerPoint file, use the asset extraction utility:

python3 skills/ppt-master/scripts/pptx_template_import.py "reference.pptx"

This script, located at scripts/pptx_template_import.py, extracts SVGs and metadata from legacy PPTX files to accelerate template creation.

Step 2 – Validate SVGs with svg_quality_checker.py

Before registration, validate that your SVGs obey PPT-safe constraints to prevent rendering errors during export. Run the quality checker against your template directory:

python3 skills/ppt-master/scripts/svg_quality_checker.py \
    skills/ppt-master/templates/layouts/my_company --format ppt169

The svg_quality_checker.py script ensures that viewboxes, font references, and path data conform to the engine's requirements.

Step 3 – Register in layouts_index.json

Add a top-level entry to templates/layouts/layouts_index.json to make the template discoverable. This file functions as a flat JSON map that the runtime consults when a template trigger fires:

{
  "my_company": {
    "label": "My Company",
    "summary": "Corporate branding template",
    "keywords": ["Corporate", "Brand", "Formal"]
  }
}

Use jq to safely append the entry without manually editing JSON structure:

jq '. + {"my_company": {"label":"My Company", "summary":"Corporate branding template", "keywords":["Corporate","Brand","Formal"]}}' \
    skills/ppt-master/templates/layouts/layouts_index.json > tmp.json && mv tmp.json \
    skills/ppt-master/templates/layouts/layouts_index.json

Step 4 – Sync the Human-Readable Catalog

After updating the machine-readable index, synchronize templates/layouts/README.md to maintain the human-facing catalog. This documentation file lists available templates with descriptions for manual selection workflows.

Phase 2: Utilizing the Registered Template in Projects

Once registered, utilizing a template requires copying assets from the global library into your project's local directories. This binds the template specifications to the generation pipeline.

Template Resolution and Copy Workflow

When you invoke a template by name (for example, "use the mckinsey layout"), PPT Master resolves the ID via layouts_index.json and executes copy commands to populate your project structure:

# Resolve template_name to ID, then execute:

cp ${SKILL_DIR}/templates/layouts/<template_name>/*.svg <project_path>/templates/
cp ${SKILL_DIR}/templates/layouts/<template_name>/design_spec.md <project_path>/templates/
cp ${SKILL_DIR}/templates/layouts/<template_name>/*.png <project_path>/images/ 2>/dev/null || true
cp ${SKILL_DIR}/templates/layouts/<template_name>/*.jpg <project_path>/images/ 2>/dev/null || true

These commands, documented in SKILL.md under the "Template Option" section, ensure that SVG layouts and image assets are available to the strategist and executor modules.

Project-Level Integration

After copying, the design_spec.md file becomes your project-level design spec. The executor reads this file alongside spec_lock.md (generated during the strategy phase) to drive SVG generation. All subsequent pipeline steps—strategist analysis, executor rendering, and post-processing—proceed exactly as they would for a free-design deck, but the layout is now anchored to your registered template.

Complete Working Example

The following bash sequence demonstrates the full lifecycle from creation to utilization:

# 1. Create a new template called "my_company"

python3 skills/ppt-master/scripts/pptx_template_import.py "reference.pptx"
mkdir -p skills/ppt-master/templates/layouts/my_company

# Generate design_spec.md and core SVGs (01_cover.svg ... 04_ending.svg)

# Then validate assets

python3 skills/ppt-master/scripts/svg_quality_checker.py \
    skills/ppt-master/templates/layouts/my_company --format ppt169

# 2. Register the template in the global index

jq '. + {"my_company": {"label":"My Company", "summary":"Corporate branding template", "keywords":["Corporate","Brand","Formal"]}}' \
    skills/ppt-master/templates/layouts/layouts_index.json > tmp.json && mv tmp.json \
    skills/ppt-master/templates/layouts/layouts_index.json

# 3. Sync README manually or via script

# 4. Initialize project and apply template

python3 skills/ppt-master/scripts/project_manager.py init my_project --format ppt169
cp skills/ppt-master/templates/layouts/my_company/*.svg my_project/templates/
cp skills/ppt-master/templates/layouts/my_company/design_spec.md my_project/templates/

# Continue with normal PPT Master pipeline (strategist → executor → export)

Summary

• Template creation involves building a package with design_spec.md and validated SVGs in templates/layouts/<template_id>/.
• Registration requires adding a JSON entry to templates/layouts/layouts_index.json and updating templates/layouts/README.md.
• Utilization copies assets from the global library to the project's templates/ and images/ directories, binding the design spec to the generation workflow.
• Validation via svg_quality_checker.py prevents runtime rendering errors by enforcing PPT-safe SVG constraints before registration.

Frequently Asked Questions

Where does PPT Master store the global template index?

The global template library index is stored in templates/layouts/layouts_index.json. This flat JSON map resolves template IDs to metadata labels and keywords when the engine detects a template trigger during project initialization.

Can I import existing PowerPoint files as templates?

Yes. Use scripts/pptx_template_import.py to extract SVGs, color palettes, and typography from existing PPTX files. This utility accelerates template creation by converting legacy presentations into the normalized asset structure required by PPT Master.

How does the executor know which design rules to apply?

The executor reads the design_spec.md file located in your project's templates/ directory. When you copy this file from a registered template during the utilization phase, it becomes the active project-level specification that governs all SVG generation and layout decisions.

What happens if SVG validation fails during registration?

If svg_quality_checker.py detects invalid viewboxes, unsupported fonts, or malformed paths, you must correct the SVG source files before registering the template. The registration process in workflows/create-template.md explicitly requires valid SVGs to prevent export failures in the generation pipeline.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}