Teach Slides

MANDATORY PREPARATION

Load the presentation-craft skill. Read its [SKILL.md](../presentation-craft/SKILL.md) and run its Context Gathering Protocol. teach-slides is the skill that protocol routes to, so here you do the gathering rather than the check.

Read [deck-spec.md](../presentation-craft/reference/deck-spec.md) for the brand.json shape you will write.

---

$ARGUMENTS

You capture the user's brand once. Every other slides skill reads what you write, so a deck comes out on-brand instead of generic. The brand lives in a .slides/ directory at the project root: context.md, brand.json, template.pptx.

For a one-step start, ../build-deck/scripts/init_brand.py --template-ref template.pptx writes a complete brand-fidelity brand.json (fidelity, template ref, fonts, colours, tokens — no layout map) straight from a template or deck — this is the fast path build-deck and narrative offer. This skill is the fuller capture: it also gathers voice, audience, and logo, and for "fidelity": "template" lets the user hand-check the layout map. Run it when the user wants that depth, or to refine what init_brand.py proposed.

If .slides/ already exists, tell the user what it holds and ask whether to refresh it or keep it. Do not overwrite without a yes.

Step 1: Check the toolchain

The renderer needs Python. Run python3 --version and python3 -c "import pptx".

If python3 is missing, tell the user to install Python 3.9 or newer. If the import pptx line fails, give them the remedy:

pip install python-pptx

On macOS with a managed Python, that command can refuse. Tell the user they can run pip install --break-system-packages python-pptx, or make a virtualenv (python3 -m venv .venv && source .venv/bin/activate && pip install python-pptx). Wait for the toolchain to work before going on. The interview can run in parallel, but Step 4 needs a working inspect_template.py.

Step 2: Interview the user

Gather the brand. You need: a template source, heading and body fonts, brand colours as hex, a logo, the usual audience, the voice, and the presenting context.

Use the AskUserQuestion tool to ask these in small batches so the user picks rather than types. Offer concrete options and an "other" path.

Ask the user these questions and wait for the answers before moving on:

• Template source. Three paths, covered in Step 3.
• Fonts. The heading typeface and the body typeface. If the user is supplying a template or deck (paths a/b), do not ask blank: Step 3 reads the fonts from the file and you confirm them here. Only ask outright for the starter path (c).
• Colours. The brand colours as hex (#1A1A2E), each with a name (ink, accent). Same as fonts: for a supplied template or deck, Step 3 reads the palette from the file and you confirm or adjust it rather than asking the user to type every hex.
• Logo. Where the logo file sits, if there is one.
• Audience. Who the user usually presents to: their role, what they know, what they walk in wanting.
• Voice. How the user's decks should sound: plain and direct, warm, formal. Ask for one deck they think sounds right.
• Context. Where these decks get shown: a boardroom, a sales call, a conference stage, a doc sent round.

Push back on vague answers. "Professional" is not a voice. Ask for a real example.

Step 3: Settle the template

A template (or an existing deck) is where the brand's identity is read from: its theme carries the real fonts and colours. Owning one is optional — in brand fidelity, the default, the pack draws every slide from tokens and the file is only an identity source; only "fidelity": "template" builds slides from its layouts. Offer three paths and let the user choose.

(a) Ingest an existing template. The user has a .pptx or .potx brand template. Take its path. This is the best case.

(b) Reuse an existing deck. The user has a finished deck whose look they like. A deck carries a theme (and masters and layouts) the same way a template does, so a real .pptx deck works as an identity source. For template fidelity, render.py strips the deck's own slides and keeps only its layouts.

(c) Generate a starter. The user has neither. In brand fidelity no template file is needed at all — the Step 2 fonts and colours go straight into brand.json and the pack draws the rest. If the user wants a real file anyway (to open and refine in PowerPoint, or for template fidelity), run make_template.py with the brand fonts and colours from Step 2:

python3 ../build-deck/scripts/make_template.py --out .slides/template.pptx \
    --colours '#1A1A2E,#E94560' --heading-font Georgia --body-font Verdana

It writes an 11-layout themed starter. Layouts 0/1/2/3/5 come role-named title, title-content, section, two-column, statement. Tell the user this is a starting point they can open and refine in PowerPoint.

Copy the chosen file (a or b) to .slides/template.pptx. For path (c) the script already wrote it there.

For paths (a) and (b), read the brand straight out of the file instead of making the user type it. Run extract_brand.py on the copied template:

python3 ../build-deck/scripts/extract_brand.py .slides/template.pptx

It prints JSON {template, fonts:{heading,body}, colours:{name:#hex}, layouts:[...], tokens:{colour_roles}} — the theme's real heading/body fonts and its palette (accent1 as accent, then accent2..accent6, plus ink and paper), the layouts (only needed for template fidelity, Step 4), and the colour-role assignments (grid and type scale are the pack's own defaults, so they are not emitted). Show the user what you read and let them confirm or adjust it: rename a colour, drop one they do not use, add a muted or spend the theme lacks. Use the confirmed values as the fonts and colours you write in Step 5. Because extract_brand.py already returns the layouts, paths (a)/(b) can skip the separate inspect_template.py call in Step 4 and map roles from this output. Path (c)'s starter was themed from the Step 2 answers, so it needs no extraction.

Step 4: Map the layouts (template fidelity only)

This step exists only for "fidelity": "template" — in brand fidelity, the default, the renderer draws every role from tokens and reads no layout map, so skip straight to Step 5. For paths (a)/(b) you already have the layouts from the Step 3 extract_brand.py output — use those. Only for path (c) run inspect_template.py on the chosen template:

python3 ../build-deck/scripts/inspect_template.py .slides/template.pptx

It prints JSON: {template, layouts:[{index,name,placeholders:[{idx,type}]}]}. Show the user the layouts you found: index, name, and placeholder count for each.

Map the six semantic roles to layout indices:

| Role | Wants | Placeholders needed | |------|-------|---------------------| | title | the opening slide | 2 to 3 | | title-content | a heading and its content | 2 to 3 | | two-column | a comparison or pairing | 2 to 3 | | quote | a quotation with room | 2 to 3 | | section | a divider | 1 | | statement | one hero idea | 1 |

A role assigned to a layout with fewer content placeholders than the role has fields fails at render time. Pick layouts with enough room. quote may point at the same layout as section if no dedicated quote layout exists.

Confirm the mapping with the user before writing it.

Step 5: Write the brand

Write three files into .slides/ at the project root.

brand.json is what the renderer reads. The primary shape is brand fidelity — identity only (fidelity may be omitted; "brand" is the default). template is an optional pointer back to the identity source; write it as template.pptx, relative to brand.json itself, so .slides/ stays self-contained. An optional tokens block overrides the pack defaults per key.

{
  "fidelity": "brand",
  "template": "template.pptx",
  "fonts": { "heading": "Georgia", "body": "Verdana" },
  "colours": { "ink": "#1A1A2E", "accent": "#E94560" }
}

The alternative is template fidelity — the pre-v0.17 placeholder-fill, for a user whose template genuinely is good. It requires template and the Step 4 layout_map:

{
  "fidelity": "template",
  "template": "template.pptx",
  "fonts": { "heading": "Georgia", "body": "Verdana" },
  "colours": { "ink": "#1A1A2E", "accent": "#E94560" },
  "layout_map": {
    "title": 0, "title-content": 1, "section": 2,
    "two-column": 3, "statement": 5, "quote": 2
  }
}

context.md is for a person and for the other skills to read. Write the voice, the audience norms, the presenting context, the identity source described in plain words, and — for template fidelity — the layout map with a line on why each role points where it does.

template.pptx is the chosen template, already copied in from Step 3.

Tell the user the brand is captured, name the three files, and point them at /slides:narrative to shape their first deck.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jameshemson
• Source: jameshemson/slides
• License: MIT

Install and usage instructions live in the source repository linked above.