presentation

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkDeclared2 observations
• ShellNone observedNo commands run in the source
• DependenciesNot pinnedSome versions float
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

sdk/packages/node/iii/local.yml

clsx, marked, mermaid, react, react-dom, tailwind-merge, @tailwindcss/vite, @types/node

Never run `vercel`.

never write a non-markdown file under `tech-specs/`.

Audit 0.4.1 · source sha 5c5284905316 · 31 Oct 2026Report an issue or request a re-scan

• Publisheriii-hq GitHub organizationOwner of the repository this skill is read from
• Source folderiii-hq/iii/skills/presentationThe exact folder we audited
• LicenceNot declaredAs the repository states it
• Commit pinned for this verdict5c5284905316A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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…

---
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**: read `<repo>/tech-specs/README.md` — the
  pointer names the base dir (in iii: `website/roadmap/`). Fallback:
  search for a dir containing both `COMPONENTS.md` and a shared `src/`.
  Detect its shape:
  - **integrated base** (shared `src/` + `scripts/manifest.mjs`, no
    package.json or build.mjs of its own — iii's shape: the site's Astro
    pages at `website/src/pages/roadmap/` render each deck's `src/App.tsx`
    as a React island via the base's `src/DeckHost.tsx`; deps live in the
    `iii-website` package) → use it, and scaffold content layers only;
  - **standalone base** (`build.mjs` + own `package.json`, one `index.html`
    per deck — the `base/` snapshot's shape) → use it;
  - **absent** → first run in this repo: pick the location with the user
    (default `website/roadmap/` when `website/` exists, else
    `roadmap/` at the repo root) and scaffold it in Phase 3;
  - **legacy layout** (`tech-specs/build.mjs` + `_gallery/` — per-deck
    standalone projects) → stop and offer the port procedure in
    `reference/hosting.md` before generating anything new.
- Output location is `<base>/<slug>/`. If it exists and is non-empty, ask:
  overwrite, update in place, or abort. **Never write a non-markdown file
  under `tech-specs/`.**
- Detect the install mode: workspace (repo `pnpm-workspace.yaml` lists the
  base) vs standalone (`pnpm install --ignore-workspace` inside the base).

### 1. Deep ingest (read, do not skim)

- Read the spec `README.md` in full first: thesis, architecture, principles,
  cross-cutting contracts, migration overview. Note whether it already has a
  frontmatter block (title/tagline/date/tags/status).
- Read every domain doc. For each, capture: the one load-bearing phrase, the
  pain it removes, the mechanism, any schema/fields, any sequence/lifecycle,
  any numbers, any honest trade-off.
- Build a **content inventory** (architecture, protocol/wire contract,
  lifecycle, state model, config schema, security, migration, ...). This is the

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-31
   ✓SAFE B 89 / 100

   first audit · source 5c5284905316

Questions about presentation

• github.com/iii-hq/iii/tree/main/skills/presentation — the audited source at commit 5c5284905316 and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology