Presentation

Presentation skill

Build evolving-scene presentations: one shared diagrammatic canvas where entities morph across steps while captions and navigation guide the audience. Each presentation is a self-contained folder under src/presentations// that composes the reusable scene kit at src/presentation-kit/.

When to use

• User asks to create, build, or generate a presentation or talk
• User asks to modify, update, or add steps to an existing presentation
• Project lacks the scene kit or presentation infrastructure and needs bootstrapping
• User asks to update, resync, or pull the latest scene kit into a project whose

vendored src/presentation-kit/ has fallen behind the skill (see [Updating the vendored kit](#updating-the-vendored-kit))

Procedure

Work through these phases in order. Do not skip self-verify.

1. Gather requirements

Ask one question at a time. Cover:

1. Topic — what the presentation is about
2. Visual style — accents, mood, density (sparse diagram vs. rich layout)
3. High-level sections — the major parts of the story, in order
4. Each step — after the sections are agreed, flesh them out one by one.

A "step" means one navigable beat in the presentation: the caption/title plus the scene state shown for that moment.

1. Per-step visuals — which entities appear, how they relate, and what

morphs between steps

Rules:

• Do not assume details the user can still provide
• Allow the user to proceed with partial detail and iterate later — no hard

completeness gate

• Do not start by asking how long the talk should be or how many steps it

should have. First establish the high-level sections, then expand each section into steps. Ask about length/count only after that structure exists, or when the user explicitly asks the agent to decide or fill in details.

• If the user says the length/count is TBD, accept that and continue by shaping

the high-level sections before implementing any steps.

• Define skill-specific terms the first time they are used in user-facing

conversation. For example: a "step" is one navigable beat of the talk; a "hero" entity is the main visual object that carries continuity across the scene. Do not front-load a glossary; define terms just before they matter.

• If the prompt already contains topic, style, and all step details, proceed to

scaffold/generate without further questions

• For key or complex steps, optionally draw an ASCII mockup of the layout

and ask the user to confirm before building. Use mockups selectively, not for every step

2. Resolve target + scaffold if needed

Before creating or modifying a presentation, ensure three contract anchors exist. Detection is contract-level (presence of the anchor, not byte-identical files). Cosmetic differences do not trigger re-scaffolding.

| Anchor | What to look for | |--------|------------------| | Build setup | vite.config.ts, package.json with a build script | | Scene kit | src/presentation-kit/types.ts, Presentation.tsx, Stage.tsx | | Presentation index | src/presentations/index.ts exporting a presentations registry |

Target resolution:

| Context | Scaffold location | |---------|-------------------| | Empty directory, or an existing standalone JS app (a package.json at the root, non-monorepo) | Repository root (.) | | Monorepo (workspaces in package.json, pnpm-workspace.yaml, or packages/ / apps/ layout) | Self-contained app under presentations/ | | Non-empty repo that is not a JS app (no root package.json — e.g. a Python/Go/Rust project) | Self-contained app under presentation/ | | Anchors already present | Use existing app; scaffold only missing anchors |

Monorepo detection signals: package.json workspaces, pnpm-workspace.yaml, or files under packages/ or apps/.

Why non-JS repos nest: the bootstrap is a full Vite + React app. Dropping its package.json, vite.config.ts, and src/ at the root of a Python/Go/Rust repo would collide with the existing project, so the scaffold lands in a dedicated presentation/ subfolder instead. Only a truly empty directory or a repo that is already a JS app gets scaffolded in place at the root.

Scaffolding steps:

1. Determine which anchors are missing (all, some, or none)
2. Copy missing pieces from templates/bootstrap/ in this skill directory.

Template paths are relative to this SKILL.md file, not necessarily to the user's current working directory. The bootstrap package.json ships a neutral presentation-app name — rename it to suit the target project (e.g. the repo or monorepo package name) before installing.

1. Install dependencies — never assume they are present. The scaffold must

ensure this full set:

• Runtime: react, react-dom, motion, lucide-react
• Dev/build: vite, @vitejs/plugin-react, typescript,

@types/react, @types/react-dom, @types/node, the eslint stack (@eslint/js, eslint, eslint-plugin-react-hooks, eslint-plugin-react-refresh, globals, typescript-eslint), and playwright (for render checks)

1. Run npm install in the resolved target directory

Non-empty project without scaffolding: state the resolved target location (e.g. "I will scaffold into presentations/") and proceed only after the user confirms.

Already scaffolded: skip scaffolding and go directly to generate/modify.

Utility helpers in scaffold.ts (alongside this file) implement anchor detection, monorepo heuristics, and target resolution for automated checks.

3. Generate or modify

Create a new presentation

1. Derive a slug from the title (kebab-case, e.g. how-to-use-this-skill)
2. Create src/presentations// from templates/presentation/:

• entities.ts — stable layoutId namespace for every morphing entity
• steps/*.tsx — one file per step; each exports a Step object
• Talk.tsx — imports all steps, renders ``

1. Add presentation-owned styling if the user wants a designed look. The kit is

BYO styles: no colors, fonts, borders, spacing scale, or framework defaults are provided by the scaffold. Default to plain CSS in a presentation-local stylesheet. Use Tailwind or another styling system only when the host project already uses it or the user explicitly requests it.

1. Register in src/presentations/index.ts:

{
  slug: '',
  title: '',
  load: () => import('.//Talk'),
},

1. Preserve all existing registry entries — new presentations must not break others

Modify an existing presentation

1. Identify the target from the user's request
2. If unspecified or ambiguous, lists the existing presentations from

src/presentations/index.ts and asks which to modify

1. Ask only about the requested changes (steps, entities, style) — do not

re-walk the full create flow

1. Make scoped edits to that presentation's entities.ts, steps/*, or Talk.tsx

4. Self-verify

Before reporting success:

1. Run npm run build in the presentation app directory — must complete with no

type errors

1. Run a render check on the presentation route — at minimum, the first step

must render without runtime or console errors. Use npm run verify when available (full multi-step check), or start npm run preview and open the route in a browser / Playwright

1. Run a visual composition check in a browser. Capture or inspect

screenshots of the first step, the last step, and any dense/key steps at a normal desktop viewport; for responsive-sensitive presentations, also inspect a narrow viewport. Prefer npm run inspect -- when available; it writes project-local screenshots under artifacts/presentation-inspection/ so Playwright resolves from the project's installed dependencies. The helper waits for morph/fade animations to settle before each screenshot and prints advisory warnings for text/chrome collisions, visually identical active navigation states, and unpolished attribution. Check the screenshots and warnings for accidental overlap, clipped/off-canvas content, unreadable stacking, missing active TOC/progress styling, and collisions with chrome such as captions, progress dots, table of contents, or navigation buttons. npm run verify catches crashes and console errors; it does not prove the scene is visually correct.

1. If any check fails, fix the issues and re-check — never report success

on broken output

If Chromium is missing, run npx playwright install chromium. Do not run --with-deps unless the environment has OS package privileges and actually needs browser system dependencies.

Output format

Report completion in this structure:

1. Action — created or modified, with presentation title and route (/)
2. Files changed — list of paths written or edited
3. Verification — commands run (npm run build, render check), visual

composition check performed, and their result

1. Follow-ups — any unresolved questions or partial details the user may want to iterate on (omit if none)

Updating the vendored kit

The scene kit is vendored (shadcn-style): every project owns a copy at src/presentation-kit/ rather than depending on a package. That copy does not update itself when the skill does — there is no version to bump. When the skill ships a kit fix (a new prop, a bug fix), a project's copy must be resynced.

The source of truth is the snapshot this skill ships at templates/bootstrap/src/presentation-kit/, refreshed whenever the plugin is updated (claude plugin update). The sync-kit.mjs script (alongside this file) diffs that snapshot against a project's vendored copy and rewrites it on demand.

When to resync: the user reports the kit is out of date, asks to pull kit updates, or a kit fix shipped in the skill needs to reach an existing project.

Steps (run from the consuming project root):

1. Report drift — diff the project's copy against the snapshot:

``bash node /sync-kit.mjs ``

Exit 0 = in sync; exit 1 = files differ (the diff is printed). Local edits to the vendored copy show up as drift too — that is expected, like shadcn diff.

1. Apply — rewrite the project's copy to match the snapshot:

``bash node /sync-kit.mjs --apply ``

Added and changed files are written; target-only files are left untouched (the script never deletes), so local-only additions survive. Pass an explicit path as the last argument to target a non-default kit location.

1. Re-apply local theming, then verify — if the project had local edits the

snapshot overwrote, review with git diff and re-apply them. Then run npm run build and a render check (per [Self-verify](#4-self-verify)) before reporting done.

Resyncing the kit does not touch a project's presentations or its host config (the ` props it passes) — only the kit files. If a kit update adds a capability the host should opt into (e.g. a new slot), call that out so the user can wire it up in their Talk.tsx`.

Composing the scene kit

Presentations import from src/presentation-kit/. Each presentation supplies only its own entities and step scenes.

Step contract

interface Step = Record> {
  id: string          // stable key for AnimatePresence
  era: string         // table-of-contents section label
  title: string      // presenter-mode one-liner
  caption: string    // browse-mode paragraph
  groupKey?: string  // consecutive steps with same groupKey are not remounted
  payload?: P
  Scene: ComponentType }>
}

For strongly typed grouped scenes, define a payload type and use Step for the steps, scene props, and ` boundary instead of casting each payload`.

type PhasePayload = { active: 'idea' | 'system'; count: number }

function GroupedScene({ step }: { step: Step }) {
  const payload = step.payload
  return {/* render from payload */}
}

const STEPS: Step[] = [
  {
    id: 'idea',
    era: 'shape',
    title: 'The idea appears',
    caption: 'A first shape lands.',
    groupKey: 'main-scene',
    payload: { active: 'idea', count: 1 },
    Scene: GroupedScene,
  },
]

export default function Talk() {
  return 
}

Entity continuity (layoutId)

Define stable ids in entities.ts. Any node that should morph across steps must use the same layoutId:

export const ENTITIES = { hero: 'hero', flow: 'flow' } as const

Smooth morph authoring rules

The original reference implementation relies on authoring discipline as much as kit code. Follow these rules when generating or modifying step scenes:

• Use a persistent scene with shared groupKey and step.payload for

consecutive beats that represent one evolving diagram. Do not split a single evolving picture into many unrelated Scene components unless the whole composition should intentionally remount.

• Put stable layoutIds only on the entity that should morph. A new visual

object gets a new id; the same conceptual object keeps the same id.

• Do not put transform or opacity styling directly on an element with

layoutId (scale, rotate, opacity, or Tailwind equivalents such as scale-*, rotate-*, opacity-*). Motion uses transforms and opacity during layout projection; combine those on a child or wrapper only when it is not the shared layout entity.

• Do not put conflicting positioning styles on one element, especially

position: relative plus position: absolute through mixed classes. For relative offsets, use relative positioning and offsets without adding absolute positioning; for true absolute placement, put the absolute positioning on a non-layoutId wrapper and verify the layout still matches the intended design.

• When fixing a smooth-morph issue in an existing presentation, preserve the

intentional composition. If cards or callouts are meant to overlap, keep that overlap and move only the unsafe positioning/opacity/transform utilities to a wrapper. Do not flatten, spread out, or otherwise redesign the scene just to satisfy the wrapper rule.

• Use Appear only for newcomers. Continuing entities with a shared layoutId

should persist and morph; they should not fade out and back in.

• Let the layout re-center; do not pin it. The signature move of an

evolving scene is that each step lays itself out around whatever is currently on screen and then re-aligns when the next entity appears — one box centered alone, two boxes balanced, a row that spreads to frame the tray that grew beneath it. Because every entity carries a layoutId, those re-alignments animate for free. Achieve it by keeping the composition content-sized and centered (natural widths, justify-content/align-items: center, align-self: stretch to match a sibling's width), and let flow do the positioning. Do not freeze positions with fixed pixel/ch widths, fixed stage widths, reserved empty slots, or align-items: flex-start pinning — those hold entities still across steps and kill the re-centering, which is the most striking thing the framework does. If two entities must share an edge (e.g. a header row framing a panel below it), give them a shared width by construction (align-self: stretch against a common parent, or one CSS var both consume) rather than hardcoding a number. When you need to stop a transient overshoot during a swap (an exiting element and an entering one briefly widening a row), stack them in one grid cell — do not solve it by fixing the whole row's width.

• Keep browse-mode chrome in mind while composing scenes. The table of contents

can occupy the left side on wide browse viewports, and captions/progress/nav occupy the lower band. Avoid dense horizontal rows that only fit the raw 880px stage in isolation;

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Codagent-AI
• Source: Codagent-AI/and-scene
• License: MIT

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