This is a mechanical contract, not a style guide.
Pitch is medium-neutral — slides keep their own look. The
skill tells your agent how Pitch's viewport, file watcher, and
present-mode keybindings work, so the artifacts it writes show up
on stage without re-work.
The slide shape
Design for ~16:9. Pitch's window is resizable but
16:9 is the canonical presentation aspect — don't author
portrait or 4:3 layouts. Lead with above-the-fold content; vertical
scroll works, but assume the viewer may only see what's visible
at first paint. Each slide is self-contained — no shared
site-wide headers, footers, or nav. Set an explicit
body { background: ... } so the slide doesn't
show through to the deck's black or white background.
Six file kinds
Default to HTML for generated slides. Other
options:
.html- Default. Interactive, scripts run, can load external resources.
.md- Plain prose. Rendered as a single scrollable slide.
.pdf- Use if the source is already a PDF; don't generate new ones for slides.
.png / .jpg / .svg- Pre-rendered visuals.
Remote URLs (Salesforce, Gong, Figma) are added by the user
through Pitch's editor, not through filesystem
writes. Don't try to "add a remote slide" by writing into the
manifest.
What works inside a slide
HTML slides render in an Electron WebContentsView
— a full Chromium browser. Modern web stack, no
compatibility quirks.
Works: all standard web APIs
(fetch, XHR, WebSockets, ES modules,
async/await, localStorage,
Canvas, WebGL, SVG, CSS animations), network access (REST APIs,
CDN assets, auth-protected endpoints), interactivity (clicks,
form input, hover, drag/drop).
Doesn't work: no native OS access from slide JS,
no IPC with Pitch chrome, no shared state between slides —
each loads fresh.
Reserved keys in Present mode — Pitch
intercepts these; slide JS won't see them. Left/Right, Space,
Shift+Space, PageUp/PageDown, Home/End drive deck navigation;
F toggles fullscreen; B blacks out; Esc exits Present. Up/Down
scroll within the slide if it scrolls, otherwise pass through.
Don't bind slide-internal actions to any reserved key.
Live reload — write atomically
Pitch watches every referenced file and reloads the open slide on
change (~150ms). The one rule that makes the iterate-with-AI loop
work:
Write each file atomically. Write to a temp file then
rename() into place, or use your tool's atomic-write
primitive. Never write a partial file at the slide's path.
If your agent writes incrementally (open → truncate →
stream → close), Pitch will catch an intermediate state and
the viewer sees a half-rendered slide. This applies equally to
imperative writes ("rewrite slide 3 now") and scheduled writes
("regenerate this dashboard every 15 minutes"). Cadence doesn't
matter; per-write atomicity does.
Stamp time-sensitive data
If a slide displays data fetched at generation time (dashboards,
status pages, anything with numbers), include a visible
timestamp the viewer can read. Pitch's live reload tells the
system the HTML changed; it does not tell the viewer the
data is fresh. A six-hour-old dashboard looks identical
to a one-minute-old one without one. Even a small
Generated: <ISO timestamp> footer is enough.
Filename hygiene
The filename surfaces in Pitch's slide rail. For HTML and
Markdown, Pitch auto-detects the rail title from the file's
<title> tag or first <h1>.
Use clear, descriptive filenames like
pipeline-overview.html, not output-1.html
or dashboard_2026_05_20.html. Don't include
timestamps or UUIDs in filenames — they make the rail
unreadable.
Paths and the .pitch manifest
A Pitch deck is a .pitch JSON file at
<project-root>/pitch/<name>.pitch.
References inside it are project-relative paths. Slide files
themselves can live anywhere inside the project root.
Rules of thumb: write slide files inside the project root (the
folder containing the pitch/ subfolder). Don't write
into the pitch/ subfolder — that's manifest
territory. Don't edit the .pitch manifest unless
explicitly told to; slide order, titles, and inclusion are
user-curated through Pitch's editor.
The manifest description field
The .pitch manifest has an optional
description field (≤500 chars) authored in the
editor's settings popover under "Notes." When present, your
agent reads it first — it's the freshest signal of who the
deck is for and what shape it should take. Example:
"For the senior leadership review on June 12. Audience: exec
staff. Tone: informative and direct."
If description is absent or empty, the skill falls
back to README.md at the project root if one exists.
Both are additive when present.
What the skill tells your AI not to do
Don't unify slide styling. Don't write a 2,000-word essay and
call it a slide. Don't edit the .pitch manifest.
Don't add navigation, headers, or breadcrumbs that assume a
multi-page site. Don't use timestamped or UUID filenames. Don't
stream partial content into a slide file. Don't bind
slide-internal interactions to reserved keys. Don't display
time-sensitive data without a timestamp.