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

> Learn how to register and use custom templates in PPT Master. Follow our guide to add JSON entries and template assets for seamless integration into your generation workflow.

- Repository: [HugoHe/ppt-master](https://github.com/hugohe3/ppt-master)
- Tags: how-to-guide
- Published: 2026-04-24

---

**Register a custom template in PPT Master by adding a validated JSON entry to [`templates/layouts/layouts_index.json`](https://github.com/hugohe3/ppt-master/blob/main/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`](https://github.com/hugohe3/ppt-master/blob/main/templates/layouts/layouts_index.json)** – The central registry that maps template IDs to metadata.
- **[`design_spec.md`](https://github.com/hugohe3/ppt-master/blob/main/design_spec.md)** – The project-level specification that drives SVG generation and layout decisions.

According to the source code in [`workflows/create-template.md`](https://github.com/hugohe3/ppt-master/blob/main/workflows/create-template.md), registration is Step 6 of the creation process, while utilization follows the "Template Option" branch documented in [`SKILL.md`](https://github.com/hugohe3/ppt-master/blob/main/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`](https://github.com/hugohe3/ppt-master/blob/main/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:

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

```

This script, located at [`scripts/pptx_template_import.py`](https://github.com/hugohe3/ppt-master/blob/main/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:

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

```

The [`svg_quality_checker.py`](https://github.com/hugohe3/ppt-master/blob/main/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`](https://github.com/hugohe3/ppt-master/blob/main/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:

```json
{
  "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:

```bash
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`](https://github.com/hugohe3/ppt-master/blob/main/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`](https://github.com/hugohe3/ppt-master/blob/main/layouts_index.json) and executes copy commands to populate your project structure:

```bash

# 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`](https://github.com/hugohe3/ppt-master/blob/main/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`](https://github.com/hugohe3/ppt-master/blob/main/design_spec.md) file becomes your **project-level design spec**. The executor reads this file alongside [`spec_lock.md`](https://github.com/hugohe3/ppt-master/blob/main/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:

```bash

# 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`](https://github.com/hugohe3/ppt-master/blob/main/design_spec.md) and validated SVGs in `templates/layouts/<template_id>/`.
- **Registration** requires adding a JSON entry to [`templates/layouts/layouts_index.json`](https://github.com/hugohe3/ppt-master/blob/main/templates/layouts/layouts_index.json) and updating [`templates/layouts/README.md`](https://github.com/hugohe3/ppt-master/blob/main/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`](https://github.com/hugohe3/ppt-master/blob/main/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`](https://github.com/hugohe3/ppt-master/blob/main/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`](https://github.com/hugohe3/ppt-master/blob/main/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`](https://github.com/hugohe3/ppt-master/blob/main/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`](https://github.com/hugohe3/ppt-master/blob/main/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`](https://github.com/hugohe3/ppt-master/blob/main/workflows/create-template.md) explicitly requires valid SVGs to prevent export failures in the generation pipeline.