# Teach Slides

> Capture a user's brand once (template, fonts, colours, voice, audience) into a project .slides/ directory the other slides skills read.

- **Type:** Skill
- **Install:** `agentstack add skill-jameshemson-slides-teach-slides`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jameshemson](https://agentstack.voostack.com/s/jameshemson)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jameshemson](https://github.com/jameshemson)
- **Source:** https://github.com/jameshemson/slides/tree/main/source/skills/teach-slides

## Install

```sh
agentstack add skill-jameshemson-slides-teach-slides
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## 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.

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

```json
{
  "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](https://github.com/jameshemson)
- **Source:** [jameshemson/slides](https://github.com/jameshemson/slides)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jameshemson-slides-teach-slides
- Seller: https://agentstack.voostack.com/s/jameshemson
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.