presentation

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: presentation
description: >-
  Turn a tech-spec directory into an interactive, marketing-grade web
  presentation — built so engineers understand the design, the reader is
  convinced of the why, and the result is shareable in public. Use when someone
  wants a spec turned into a deck.
---

# Presentation

Turn a technical specification into an interactive, persuasive web deck —
the kind at iii.dev/roadmap/. The output is a **content layer** inside the
repo's roadmap base (the shared component library, gallery, and markdown
spec viewer that build every deck into one static site — Astro routes of the
site package in iii, a standalone Vite project in other repos):

1. helps engineers **understand** the spec — the architecture is a navigable
   map, not prose;
2. is **interactive** — steppable diagrams, a selectable system map, live
   toggles; interactivity is what makes it stick;
3. reads like **marketing** — it argues the *why*. if no one is convinced the
   work should happen, the spec has not done its job;
4. is **build-in-public ready** — each deck ships as a static page at
   `/roadmap/<slug>/`, safe to share.

## Comparable to

A product launch microsite generated from an RFC. Stripe-doc clarity meets a
keynote narrative, in a monospace drafting-sheet style.

## Activation

### Use For

- generating an interactive deck from a tech-spec directory
- refreshing or extending a presentation already generated by this skill

### Do Not Use For

- writing the spec itself — use `/tech-spec`
- static slide exports (pdf / keynote) — use a slide tool
- general UI work unrelated to a spec — use `/design`

## Load First

Read these before building (they are the law — do not re-derive them):

- `reference/design-system.md` — the locked tokens, type, motion, layout
- `reference/archetypes.md` — the interactive slide library + how to pick one
- `reference/component-standards.md` — deck-local vs promoted components, the
  promotion checklist, the registry format
- `reference/narrative-framework.md` — the persuasive arc + outline rules
- `reference/quality-bar.md` — the checklist to self-verify before finishing
- `reference/hosting.md` — the two-tree layout, the pairing contract,
  frontmatter registration, and deploy
- **per repo:** `<base>/COMPONENTS.md` — the live registry of that repo's
  shared components. It may exceed the bundled catalog; when it and
  `reference/archetypes.md` disagree, **the repo registry wins**.

The skill bundles two scaffolds:

- `template/` — one deck's **content layer** (App, sections, pages, content
  data, the spec-docs glob). Copy it per spec; everything visual comes from the
  base's shared `src/` via the `@lib` alias. You generate only content.
- `base/` — the whole per-repo presentations site: the shared component
  library + design tokens, the gallery, the md-only spec viewer, and the build
  glue (`build.mjs`, `vite.config.ts`, one `package.json`). Copy once per repo
  (in iii it already lives at `website/roadmap/`); per-deck runs never
  modify it except **additive component promotion** per
  `reference/component-standards.md`.

## Progress Updates

Emit one short line before each phase: `ingesting spec` → `reading the
component registry` → `proposing outline` → `scaffolding` → `generating slides
(k/N)` → `registering spec frontmatter` → `verifying`.

## Workflow

Phases are gated. Do not skip Phase 2's approval or Phase 5's verification.

### 0. Resolve inputs

- The argument is a tech-spec directory: `<repo>/tech-specs/<slug>/` —
  **markdown only** (README.md + domain docs; frontmatter in README.md). If
  given a path elsewhere, resolve into the spec tree or ask.
- The **slug is the spec directory's basename** (e.g. `2026-06-21-devexp` —
  `YYYY-MM-DD-<name>`; the day prefix orders the roadmap timeline). It is
  the deck directory name AND the URL segment — the pairing contract in
  `reference/hosting.md`. Fix it now and use it everywhere; never prettify it.
- Resolve the **base project**