skills/new-demo/SKILL.md

17 KB · Oct 4, 2026 · 12:23 UTC

---
name: new-demo
description: This skill should be used when someone asks for a product demo, walkthrough, tutorial, onboarding flow or "show how my product works" and there is no Rendemo project yet — including "make me a demo", "demo my app", "turn this into an interactive demo", "record a walkthrough of X", or a bare product URL with a request to demo it. Read it BEFORE choosing how to capture (a user recording with the Rendemo Chrome extension beats a browser capture code, which beats a headless crawl) and before rendemo_crawl_site, rendemo_start_browser_crawl or rendemo_list_projects on an empty workspace. Covers the two questions to ask first, the intent-to-theme recipes, the extension handoff script to hand the user verbatim, the build pass from auto-directed draft to published link, and translating plain-words feedback into edits — so the user never has to open Rendemo at all.
version: 1.0.0
---

# Starting a demo from a conversation

Someone has asked you for a demo. They have not asked for a project, a capture, a sandbox, a theme
or a publish step — those are our nouns, and every one you make them learn is a reason to give up.
The job is to get from "I want a demo of X" to a live link they can send someone, with the person
doing exactly one thing: showing you their product once.

Assume they will never open Rendemo. Everything below exists to make that assumption true.

**One rule before any of it: waiting is a tool call, not a turn.** Recording, crawling and building
all take minutes, and every tool here that waits on one — `rendemo_watch_captures`,
`rendemo_get_crawl_status` — holds the connection open and returns when something actually happens.
When one comes back still-not-finished, call it again immediately. Do not summarise the wait, do not
ask the user to check, and do not end your turn: nothing on the other side will resume it, and the
work you were waiting on completes into an empty room. A result that says NOT A STOPPING POINT means
exactly that.

## Two questions, then get out of the way

Ask both before any tool call. They are cheap, they are the only things you cannot infer, and each
one decides something you would otherwise get wrong.

**1. What is this demo for?** Not "what should it cover" — what job it does. The answer picks the
story shape, the theme, the motion and the ending, all at once:

| They want | The story is | Open on | End on | Theme candidates | Motion |
|---|---|---|---|---|---|
| To sell it — prospects, outbound, a website | the shortest path to the payoff | a title card naming the outcome | book a demo / talk to us | `atrium` `broadsheet` `kiosk` | `cinematic` |
| To onboard new users | first-run order, nothing clever | wherever a new account actually lands | into the product itself | `vellum` `signal` | `calm` |
| To teach one feature | one screen, deep | the screen the feature lives on | related docs, or back to the app | `signal` `console` | `calm` |
| A launch or landing-page loop | a highlight reel that autoplays | the most striking moment in the product | sign up / join the waitlist | `marquee` `sticker` | `kinetic` |
| To answer "how do I…" for support | the exact task, no detours | the task's entry point | back to support / the next task | `ledger` `vellum` | `calm` |

A theme is not optional polish — **publishing refuses until one is set**, deliberately, so that no
two demos default into looking alike. Intent is how you choose one well instead of guessing.

**2. Does the demo need to show anything behind a login?** Their dashboard, their account, their
data. People rarely volunteer this, and the public marketing site is almost never the product they
meant. It decides the capture route below, and getting it wrong costs a whole crawl.

**Suggest, don't interrogate.** Lead with your read so they can just say yes: "Sounds like a sales
demo — I'd open on the outcome and end on a Calendly link, in `atrium` with cinematic motion. Want
that, or something calmer?" Two questions is the budget. Anything else you would like to know
(accent colour, step count, tone) you should decide, do, and offer to change afterwards.

## The capture ladder — a recording first

Three ways a product gets into Rendemo. They are not equivalent, and the order matters:

1. **A recording** (Rendemo Chrome extension) — the person clicks through their own product and the
extension records the real thing: rrweb DOM stream plus video, real cursor, real transitions,
real data, pages behind a login included. Auto-direction runs the moment it uploads. **This is
the best demo Rendemo can make, and it should be your default ask for anything that is a
product.**
- *If they want YOU to do the walkthrough* rather than click through it themselves — "make the
demo, I don't want to drive" — that is **agent-driven recording**: they paste one code and you
rehearse the workflow unrecorded on their signed-in tab, propose the take as a plan they approve,
then record that plan as one clean take. Same real take, same auto-direction; you navigate it.
See `drive-and-record`. A person who knows their product still tells its story best, so offer
this as the alternative, not the default.
2. **A browser capture code** (`rendemo_start_browser_crawl`) — the person pastes one code into the
extension, signed in as themselves, and **you** capture the pages through it with
`rendemo_capture_pages`. Static replica, no real interaction, but it reaches signed-in pages when
a recording is not on the table, and costs them one paste. See `sandbox-demos`.
3. **A headless crawl** (`rendemo_crawl_site`) — no human involved at all, public pages only,
honours robots.txt. Right when the demo genuinely *is* the marketing site, or when nobody is
available to record.

Reach down the ladder only for a reason. "They are in a chat and I have no browser" is **not** a
reason — the person has a browser, and every route here is one they drive. The reasons that count:
they do not have access to the product, nobody is at a keyboard, or the subject really is a public
website.

### Handing off a recording — give them this, not a paraphrase

Do not explain the extension. Give the steps:

1. Install the Rendemo Chrome extension (https://www.rendemo.com/extension) and connect it to your
Rendemo account.
2. Open your product in Chrome and sign in the way you normally would.
3. Click the Rendemo extension icon and hit **Record this tab**.
4. Click through what you would show someone — five to eight screens is the sweet spot. Do not
worry about being smooth or fast; dead air gets cut.
5. Hit **Stop**, then **Send to Rendemo**. (Stop alone does not upload — the take stays in the
extension until Send.)
6. That is everything — I am watching for it to land, so you do not need to tell me when you are
done.

Step 5 is the one that gets dropped, and dropping it looks exactly like a broken product: they
believe they have sent a recording and nothing ever arrives. Always name both buttons.

### Then wait — with `rendemo_watch_captures`, not with the user

The moment you have given those steps, call `rendemo_watch_captures`. It **holds the connection
open** for up to two minutes and returns when a recording lands, so waiting is something you do
inside a tool call rather than something you ask a person to announce. It also waits out the story
director, so what comes back is a project with a plan already worth reading.

**If it returns "nothing yet", call it again immediately with the `sinceIso` it gave you.** That
result is not news, and it is not a stopping point. This is the single most common way this whole
flow fails: the agent reports "I'll check back once you've finished recording" and ends its turn —
and nothing checks back, because a chat has no timer and no scheduler. The person finishes a
perfectly good recording into silence. Two or three consecutive waits is a normal recording.

The tool tells you when the situation has genuinely changed: after about ten minutes it stops
telling you to keep waiting and starts telling you to ask whether they pressed **Send to Rendemo**,
because at that point a slow take is no longer the likely explanation.

### What is already happening while you wait

Registering a capture queues two jobs: a prewarm, and a **`direct` pass — the story director**. So
by the time they say "done", the project usually already has steps, captions and a first cut of the
narrative. **Read it with `rendemo_get_plan` before you touch anything.** You are editing a draft,
not authoring from an empty file, and re-authoring what auto-direction already did is the most
common way to make a demo worse and slower at the same time.

### A capture-code session: they paste once, you capture

One route down the ladder the roles flip. The person pastes the capture code from
`rendemo_start_browser_crawl` into the extension, signed in, on the site — and that paste is the
whole of their job. From then on **you** name the pages: `rendemo_capture_pages({ crawlId, url,
urls })` opens each url in that signed-in tab, captures it, and holds the connection open while it
does. Send the product's real screens (the dashboard, a list, a detail view, settings), not the
marketing site, and do not ask them to click anything per page.

Read the result the way you read a watch. It says whether the extension has joined at all — "nobody
has pasted the code yet" is a different situation from "working", and the tool names which — then
lists every url as captured, failed, or still in flight. In flight means call it again with no
`urls`; that is not a stopping point. A url refused as a **login wall** means the tab is not signed
in for that page: ask them to sign in there, then re-issue it. Pages they capture by hand with
"Capture this page" land in the same crawl; `rendemo_watch_captures({ crawlId })` counts everything
that reached storage either way, and is the cross-check before you finish.

There is still no event meaning "finished" — the sandbox has enough when the story does. Call
`rendemo_finish_browser_crawl` then; it verifies against storage rather than trusting the number you
pass. Do not wait for the code to expire.

## The build pass

In order. Each step assumes the one before it.

1. **`rendemo_get_plan`** — read the story that already exists. Decide what to cut before what to add.
2. **Tighten the copy.** Auto-direction names screens accurately and generically. Rewrite titles to
say what the viewer is looking at in *their* words, and blurbs to carry the thing that is not
visible. If a blurb can be deleted without loss, delete the step.
3. **`rendemo_set_demo_presentation_theme`** — `themeId`, `motionIntensity` and `accentMode` from
the intent table, confirmed by their answer. Required before publish.
4. **`rendemo_set_title_card`** — the cover, which now renders as its own beat before step 1. Name
the outcome, not the product.
5. **`rendemo_set_end_card`** — see below. Never skip this one.
6. **Check it**: `rendemo_director_lint` for geometry, `rendemo_review_step_presentations` for
whether the cards can actually be read. Lint passing is not evidence a step looks right.
7. **`rendemo_publish_demo`** — world-visible, so confirm once, at this moment, not in advance.
8. **Look at it.** `rendemo_review_demo_frames` photographs the live demo step by step and hands you
the images. See below — this is the step that catches what the others cannot.
9. **Hand back the URL** and say what you decided that they might want to veto.

### Look at the demo before you call it done

Everything up to here is blind. `rendemo_director_lint` reads geometry and passes while a card is
unreadable, sits over a busy region, or covers the very thing it points at.
`rendemo_render_step_card` draws the real card but over a stand-in shell, so it never sees the card
against the real screen. Every card defect this product has shipped lived in exactly that gap.

`rendemo_review_demo_frames` opens the published demo at each step, waits for the card to finish
arriving, and returns real screenshots as images. Look at them and fix what is actually wrong: copy
you cannot read, a card covering its target, emphasis that vanished into a light UI, text that
clipped. Then republish — same link.

Two rules that decide whether this helps or hurts:

- **The camera cannot see blur.** Headless Chrome drops `backdrop-filter`: the dim paints and the
blur does not, so a glassy theme photographs flatter and harder-edged than a viewer ever sees it.
Judge legibility and contrast; never "the glass looks wrong". The tool repeats this in every
result because it is the one way a visual check makes a demo worse.
- **A step that reads well needs nothing.** The failure mode of a review pass is finding something
to do. If five frames are fine, say they are fine.

It photographs up to six steps per call and needs the demo published, because it photographs the
real artifact at its real URL. That is why publishing comes first: publish, look, fix, republish —
the slug is kept, so nobody is ever handed a link that breaks in between.

### The end card is the difference between a demo and a video

A demo that stops has spent the whole view and asked for nothing. Before you ask them what the CTA
should be, go and find it — then ask with the answer already filled in:

- Grep the capture or sandbox for a booking or signup link: `calendly`, `cal.com`, `hubspot`,
`/demo`, `/signup`, `/get-started`, `/contact`, `/trial`.
- Match it to the intent: sales ends on a meeting, onboarding ends *inside* the product, a launch
loop ends on signup.
- Then: "I found `calendly.com/them/demo` — using that for the button unless you say otherwise."

One question, already answered, is not the same as an interrogation. Publishing warns when a demo
has no ending; treat that advisory as a defect you caused, not a note.

### Say what you chose

When you hand back the link, name two or three decisions the person can reverse: a step you cut,
a mark you chose, the ending you wired. It reads as craft rather than automation, and it is how
they learn what is adjustable without reading a manual.

## Iterating in their words

They will not say "change `scene.mark` to `spotlight`". Translate:

| They say | It usually means | Reach for |
|---|---|---|
| "step 2 is slow" | an unearned step, or a camera move on a step that did not need one | delete the step, or `rendemo_direct_step` |
| "too corporate" / "too plain" | the theme is wrong for who they are | `rendemo_set_demo_presentation_theme` |
| "I can't read that" | a card over a busy region, or an emphasis that vanishes on a light UI | `scene` `scale`/`weight`, or `spotlight` over `ring` |
| "wrong order" | the story, not the capture | `rendemo_reorder_steps` |
| "it just ends" | no end card | `rendemo_set_end_card` |
| "it doesn't look like us" | brand colour, not theme | `rendemo_design_brand_style` |

Then republish. **The slug is kept across republish**, so the link they already sent to someone
keeps working and shows the new version — "same link, already live" is always true, and worth
saying, because everyone assumes otherwise.

## Do not send them to the Studio to fix something you can fix

The Studio exists and is good, and needing it is a failure of this flow. Two exceptions worth
naming out loud: anything that needs their eyes on a frame ("does this look right to you?"), and
anything that needs a credential. Everything else — copy, order, theme, camera, ending, publish,
embed, tracking links — you can do from here.

One real hazard if they do open it: **opening `/projects/<id>` in the Studio while you are mid-pass
can revert your draft edits**, because the Studio autosaves the plan it loaded. Finish your pass,
publish, then invite them in.

## Where to go next

- `demo-craft` — the step scene: cards, marks, ties, entrances, and the rules that silently discard
a change you thought you applied. Read before any styling pass.
- `sandbox-demos` — everything specific to a crawl-backed sandbox: surveying pages, durable targets,
publish order.
- `brand-and-look` — brand kits and colour.
- `camera-direction` — zoom, framing and when a move is worth it.

## Tools

`rendemo_watch_captures` (until a recording lands and its direction finishes) → `rendemo_get_plan` →
`rendemo_update_step` / `rendemo_reorder_steps` →
`rendemo_set_demo_presentation_theme` → `rendemo_set_title_card` → `rendemo_set_end_card` →
`rendemo_director_lint` / `rendemo_review_step_presentations` → `rendemo_publish_demo` →
`rendemo_review_demo_frames` (look at it, fix, republish) →
`rendemo_get_embed` / `rendemo_create_tracking_link` → `rendemo_get_demo_analytics`.

No recording available: `rendemo_start_browser_crawl` (signed-in pages, capture code) or
`rendemo_crawl_site` (public site), then `sandbox-demos`.

SHA-256: 6da9b3bafe8153ecab5fbae90c2e7ce4ebef4d731674c650d9e3eeb7b5754061