How to
How to turn Markdown into a slide deck
chiltepin slides makes a deck from any Chiltepin document: each heading is a slide, each block an exhibit, and diagrams build step by step. Ask the agent for a deck and it writes action-title headings with one exhibit each — then the same file is also the page and the PDF.
1. Give the agent the request
Install the skill once — npx skills add jdiejim/chiltepin -g — then say what the reader needs, in plain words. Do not name a block type; picking it is the skill's job.
Show the five phases of an incident from alert to lesson, with how long each took last quarter and the target for next, as a deck for the ops review. Write docs/incident-phases.md, run chiltepin check, then chiltepin slides -p.
“As a deck for the ops review” switches the skill to deck discipline: one assertion per heading, one exhibit under it, {split} where prose and exhibit belong side by side. The gallery document for this request uses exactly that.
2. What the agent picks, and why
The skill reads the request as the reader's question and answers it with two to five blocks, each a different lens. For this request it picks:
chevrons— the five phases as a process ribbon — the slide the whole deck hangs off, one chevron per phase with what closes it, the current phase accentedchart— last quarter’s minutes per phase as bars, so the phase that dominates is visible before anyone reads a numberbignumber— the target — one figure, one label, the accent — on its own slide, which is how a target is remembered
Before writing each one it runs chiltepin block <type>, which prints the fields, enums and terse forms from the schema. It writes YAML; it never places a shape.
The block it wrote
The chevrons block the agent wrote for the incident deck in the gallery, unedited. In the deck it is the exhibit of the first content slide; on the page it is the same block.
```chevrons
id: phases
title: Incident lifecycle
current: 3
steps:
- { label: Detect, desc: "alert fires, on-call paged", accent: navy }
- { label: Triage, desc: "severity set, commander named", accent: navy }
- { label: Mitigate, desc: "customer impact stopped", accent: amber }
- { label: Resolve, desc: "root cause fixed and deployed", accent: navy }
- { label: Review, desc: "postmortem published in 5 days", accent: navy }
```3. Check it
The agent runs npx -y chiltepin check docs/<file>.md --json. Every diagnostic has a stable code, the file and line, and a hint. One it might see on a first draft:
E_SCHEMA docs/incident-phases.md:19 chevrons: unknown field 'duration'
hint: Valid fields: label, desc, accent. (The durations went into the chart on the next slide instead.)It fixes what the hint says and re-runs the check. A change is not done until the check passes — and in CI the same command fails the build, so a document cannot drift silently.
4. Render it
npx chiltepin slides docs/incident-phases.md -p opens the deck; arrow keys move between slides and through builds. -o deck.html writes a single self-contained file to send. chiltepin build emits the page and the deck for every document with a toggle between them, and chiltepin pdf prints either.
See it done
The agent-written document for this request is in the gallery: The incident process, shown exactly as generated from “Deck opener for the incident process — the phases, and which one we are improving this quarter.”. Related: the slides guide, the deck template, and the blocks chevrons, chart, bignumber.
Frequently asked questions
- How does Markdown become slides?
- Every top-level heading starts a slide and is its title; the prose and blocks under it are the slide’s content. The meta block is the cover. A normal document therefore already presents; a document written for a deck keeps one idea per heading and one strong exhibit each. Long sections paginate automatically by a content budget.
- Can I control the layout of a slide?
- With a marker on the heading: {split} puts prose left and the exhibit right, the consulting layout; {top}, {center} and {bottom} force alignment; {nobuild} shows a diagram whole instead of building it. Everything else — sizing, spacing, the footer with the page number — is the renderer’s.
- What are builds?
- Diagrams with a natural order — sequence, flow, state, saga, spans, steps, timeline — reveal one item per keypress in the deck. Earlier items stay, the newest takes the accent, and the left arrow walks back. The page and the PDF always show the whole diagram.
- Does the deck stay in sync with the document?
- It is the document. chiltepin build emits both views of every doc — the page and a companion deck at slug.slides.html — with a toggle between them, and Studio’s Present mode shows the current doc as a deck without saving. There is no separate slide file to drift.