# Skill: Capture an Inkly demo from a URL You are an external coding agent (Claude Code, Codex, Cursor, …) running inside the user's project. Your job is to turn a request like "capture a demo of " into a finished Inkly demo ZIP of image/video steps. You plan the story and decide what to do; the Inkly CLI is the capture harness AND the page driver: it opens real Chrome, injects a recorder, hosts a navigation driver, and exports the ZIP. You drive the page through `inkly capture nav` — you do NOT attach your own browser-control library. This skill is about CAPTURING the steps. Polishing the result — validating frames, trimming stray steps, relabeling, previewing — is a separate skill; focus here on getting clean captures. For self-contained HTML output instead of image/video, use the `agent-html-capture` skill. ## Contract - Install the Inkly CLI globally, then capture the target. - Produce a ZIP exported by `inkly capture stop`, plus the unpacked demo folder. - Use only the agent-facing lifecycle: `capture start`, `capture nav` (to drive), `capture stop`, `capture cancel`. `capture status` and `capture undo` are available for inspection/recovery. - Do not pass prompts into the CLI (`capture` rejects `--prompt`); you own planning and the sequence of nav actions. - No Chrome extension is required. Do not open the Chrome Web Store or load an unpacked extension. - Drive the page ONLY through `inkly capture nav --session `. Do NOT attach Playwright/Puppeteer over CDP — the CLI hosts the driver for you. - The capture browser is a fresh, isolated Chrome profile that does NOT touch the user's everyday Chrome. Never attach to, copy, or restart their real Chrome or profile. ## Install the Inkly CLI Install the CLI globally, then confirm it runs: ```bash npm install -g @inkly-org/cli inkly version ``` Use the global `inkly` binary for capture commands. Do not run Inkly through `npx`; one-off execution can resolve Chrome differently and cause capture/browser launch failures. ### Connect the CLI if the user gives you an Inkly API key Users sometimes paste an Inkly API key (token) into the request. If you are given one, authenticate the CLI with it FIRST — before you start capturing: ```bash inkly login --token # or: export INKLY_API_TOKEN= inkly status # confirm it connected ``` Capture itself runs locally and does not require this, but connecting up front means the finished demo can be synced/published without re-authenticating, and it ties the run to the user's account. This is the Inkly PLATFORM key — it is unrelated to signing in to the site you are capturing (that is the persistent-profile flow below). If no key is provided, skip this; do not ask for one unless the user wants to publish. ## Choose what to capture You can capture either a hosted URL or the user's own app running locally. If the user did not make it clear, ask which. - A HOSTED URL (a SaaS site, marketing page, or web app the user names): use it directly as ``. - The USER'S LOCAL APP, when you are running inside its repo and they want a demo of their own product: this is usually the SIMPLEST path — no bot protection, and login is whatever their dev setup uses. Spin the dev server up for them: 1. Find the dev/start script in `package.json` (commonly `npm run dev`, `pnpm dev`, `npm start`, or a framework command). If it is ambiguous, ask which command and port. 2. Start it in the BACKGROUND and WAIT until the port actually responds (poll `http://localhost:`), not just until the command launches. 3. Use that `http://localhost:` plus the right starting route as ``. 4. Leave the server running for the whole capture; stop it when you are done. ## Tell a good story A demo is a narrative, not a tour. Before you click anything, decide the ONE sentence a viewer should believe by the end (" lets me with "), who that viewer is, and the single signature moment that proves it. Every click serves that sentence. - Lead with value, not chrome. Your first real step should land on the core value or the signature interaction — not a login screen, a settings page, or an empty dashboard. Hook first, context later. - Show the product WORKING, do not point at where it lives. A completed search with results, a populated dashboard, a command palette mid-use, a generated output, a real workflow screen — beats a static marketing page or an empty form every time. Capture the interaction in action, not just its location. - One idea per step. Each step should advance the story by exactly one beat — a new capability, a differentiator, a payoff. If a step does not change what the viewer understands, do not capture it. - Sequence value-first: hook (the aha) -> the core capability in action -> a differentiator that sets it apart -> a supporting feature -> a payoff. Put pricing and sign-up LATE, never mid-story. - Prefer populated, real states. Navigate or seed your way to data-rich screens; avoid zero-states, empty inboxes, and lorem ipsum. A viewer believes a product they can see working with real content. - Match the audience: a developer tool's signature moment is a real API call returning data; a design tool's is a real canvas edit; a CRM's is moving a real deal forward. Pick the moment that audience cares about. - Keep it tight: 5-8 steps unless the user asks otherwise, and END on the payoff you want remembered. A short, coherent arc beats a long, flat tour. ## Browser and mode `start` runs REAL Google Chrome (not Chrome for Testing — that build gets challenged; real Chrome clears most bot protection) and is HEADLESS by default (faster, no window; real Chrome passes passive Cloudflare even headless). Use `--headed` only when the USER must act in the window — to clear a challenge or sign in by hand. A headed automation window does not beat a wall on its own; it just lets the user reach it. ## Bot walls - PASSIVE protection (most Cloudflare): real Chrome renders the page, headless or headed — nothing to do. - ACTIVE challenge (a CAPTCHA/Turnstile widget, a "verify you are human" / "Just a moment..." interstitial, or "you have been blocked"): CDP-driven Chrome cannot pass it, headed or not — do NOT try to script around or evade it. If it only gates a marketing page, capture whatever rendered and report partial coverage. If it gates a login the demo needs, hand off to the user (see "Capturing a logged-in product"). ## Sign in before you record (when a demo needs an account) If it is clear — either because the USER told you so, or from your own judgment of the story — that a sign-in or sign-up is required for a successful demo (the value lives behind auth: a dashboard, a workspace, a generated result a logged-out visitor cannot reach), create the persistent profile FIRST, before the real capture: ```bash inkly capture ask-user-to-log-in --url # returns profile.name; user signs in/up by hand inkly capture start --profile --url --window-size 1440x900 ``` Recording then begins from a signed-in app, and the user is never asked to authenticate mid-capture. Do NOT start the real capture until the profile is signed in. This is also the only way to handle OAuth / "Sign in with Google", which cannot be completed inside the CDP-driven capture. Full detail — credentials you can type yourself, and reusing a saved login across runs — is under "Capturing a logged-in product" below. ## Start capture Use the target URL, a descriptive demo name, and a stable viewport (1440x900 unless asked otherwise). `--runtime cli` is the default and recommended. ```bash inkly capture start \ --runtime cli \ --url \ --name "" \ --window-size 1440x900 \ --no-video ``` Modes: - Default image mode: omit mode flags; exports PNG image steps. Click zoom/pan is on by default — pass `--no-zoom` only if the user asks. - Video motion: the `start` command above passes `--no-video` for deterministic image-only steps — the reliable default for a first capture. To capture motion instead, OMIT `--no-video`: a `nav click` that follows smooth scroll/typing then exports the preceding motion as a WebM step with a PNG poster. See the video caveat under "Drive the page with `inkly capture nav`". Optional size levers (on `start`): `--compress-images` re-encodes captured PNG/JPEG screenshots to WebP (smaller, near-lossless); `--subset-fonts` subsets any captured font assets to the glyphs used (WOFF2). Both are screenshot-only — for self-contained HTML capture use `inkly capture-html` instead. Parse the JSON output and SAVE `session.id` — every `nav`, `stop`, `cancel`, and `status` call needs `--session `. (`browser.webSocketDebuggerUrl`, `browser.debuggingUrl`, and `tab.targetId` are still printed, but with the nav contract you do not need to attach to them yourself.) ## Record steps After `start`, drive the page with `inkly capture nav`. Do not call manual capture commands and do not attach your own browser client. 1. `inkly capture nav snapshot --session ` ONCE to see the landing page (plain text tree with `@refs` — read it directly, no parsing). This should be your only standalone snapshot. 2. `inkly capture nav click "@" --session ` on a visible user-facing target to create the next step. The command echoes `url=… | steps=N` and the FRESH tree of the resulting page — read the WHOLE tree, do NOT pipe it through `head`/`sed` (that truncates the refs and forces a wasteful re-snapshot). 3. Pick your next ref from that returned tree and act again — aim for ~1 call per step. In the normal loop do NOT call standalone `nav snapshot`/`nav refs`/`nav get url`/`capture status`; the action already printed the tree, url, and step count. 4. Below-fold clicks become smooth scroll videos on their own — a `nav click` scrolls to an off-screen target first. Use a standalone `inkly capture nav scroll down --session ` then a click only for a scenic scroll over on-screen content — see the caveat. 5. To end on a payoff page, `nav click` once more on a NON-navigating element of it (an on-page heading or section anchor) — never the logo or a nav link. ## Drive the page with `inkly capture nav` Do NOT attach your own browser-control library over CDP. The CLI hosts a navigation driver inside the capture listener; you drive the page entirely through `inkly capture nav --session `, using the `session.id` you saved from `start`. Every nav verb that drives the page (click/fill/type/press/select/scroll/...) fires REAL browser input, which the capture recorder hears and records as a normal step. Driving the page IS what produces steps — there are no manual capture commands, and you never take a screenshot to CAPTURE a step. (The one exception, `nav screenshot`, is a DEBUG-ONLY escape hatch for inspecting a stuck page — it records nothing; see the verb reference.) ### Output is plain text — read it directly (no parsing, no truncating) - `inkly capture nav snapshot --session ` prints a plain indented accessibility tree (roles + names + `@refs`) STRAIGHT to stdout. Read it as-is — do NOT pipe it through python/jq/grep, there is no JSON wrapper and no `urlMap`/`xpathMap` dump to parse. Pick the `@ref` of the element you want directly from the printed tree. - Every page-driving verb (click/fill/type/select/scroll/back/...) ECHOES its own status line plus a FRESH tree: `ok | url= | steps= | ` followed by the trimmed accessibility tree of the page AFTER the action. So after a click you already have the new page's refs and the current url + step count — you do NOT need a separate `nav snapshot`, and you do NOT need `nav get url` or `capture status` mid-run. - A step that just NAVIGATED may still be committing when the command returns, so the header OMITS `steps=` and shows `step still committing` instead of a number. The click WAS recorded — do NOT re-click (that double-records); just continue with the returned tree. `capture status` has the settled count if you need it. - Do NOT pipe nav output through `head`, `tail`, `sed`, or `| head -N`. Truncating the output cuts off the refs at the bottom of the post-action tree, so you lose the very refs you need and are forced into a wasteful standalone `nav snapshot` — which is exactly the redundant call to avoid. Read the WHOLE returned tree. `--filter`/`--max-depth` apply ONLY to a standalone `nav snapshot` — an ACTION's echoed tree is always the full trimmed tree and cannot be bounded by flags. So on a long page either just read the full echoed tree, or pass `--no-snapshot` on the action and then take a bounded standalone `nav snapshot --filter ` / `--max-depth ` to find your next ref. ### The loop: snapshot ONCE → ref → act → read the returned tree → act again 1. `inkly capture nav snapshot --session ` ONCE at the start to see the landing page and its refs. This is the ONLY standalone snapshot you should need. 2. Pick the ref of the element you want (a button, link, field, tab) from the printed tree. 3. Act on that ref, e.g. `inkly capture nav click "@0-12" --session `. The recorder captures the step, and the command prints the new url + step count + the fresh tree of the resulting page. 4. Pick your next ref from THAT returned tree and act again. The returned tree IS your next snapshot — every action hands you one, so you should fall into a steady 1-call-per-step rhythm (one action = one step + the next tree). 5. In the normal loop do NOT call standalone `nav snapshot`, `nav refs`, `nav get url`, or `capture status` — the action you just ran already printed the tree, the url, and the step count. Reach for a standalone `nav snapshot` ONLY when you genuinely lost the tree (you passed `--no-snapshot`, or piped the output through `head`/`sed` and truncated it — don't do that), or need `--full`/`--filter`/`--max-depth`. `capture status` and `nav refs` are recovery/programmatic tools, not part of the capture loop. The selector slot for any verb accepts a `ref` from the latest tree (`@0-12`, `[0-12]`, `ref=0-12`, or bare `0-12`), or an XPath, or a CSS selector. PREFER refs — they are resolved from the tree you just read. Run `nav snapshot` first so refs exist; the post-action tree refreshes them automatically. Refs are valid ONLY from the MOST RECENT tree. Every snapshot (and every action's echoed tree) renumbers refs from scratch — the same on-screen element gets a different ref each time. So always pick from the tree the LAST command just printed; never reuse a ref from an earlier tree (and never hardcode one). A ref from a stale tree fails with `Unknown ref "" - run `inkly nav snapshot` first to populate refs` — if you see that, you used an old ref; re-read the latest returned tree and pick the ref from there (you rarely need a fresh standalone snapshot). ### Verb reference All verbs take `--session `. The `` slot is ref|xpath|css (prefer refs). Action verbs print the post-action tree by default; add `--no-snapshot` to suppress it or `--json` for the structured object. - `nav snapshot [--full] [--filter ] [--max-depth ] [--json]` — plain accessibility tree with refs, trimmed to interactive/heading/landmark nodes by default. `--full` prints the untrimmed tree; `--filter` keeps only nodes matching a substring or `/regex/`; `--max-depth ` caps depth; `--json` emits `{tree,urlMap,xpathMap}` for programmatic use. You rarely need this standalone — actions already return a fresh tree. - `nav refs` — print the structured ref maps (count + urlMap + xpathMap) as JSON; for programmatic callers only. - `nav click ` — click the element. The main step-producing verb. Returns the post-action tree. - `nav fill [--enter]` — set a field's value in one shot; `--enter` presses Enter after (submit a search/login). - `nav type [--delay ]` — type text into the focused element character-by-character; `--delay ` spaces keystrokes. - `nav press ` (alias `nav key `) — press a single key (e.g. `Enter`, `Tab`, `Escape`, `ArrowDown`). - `nav select ` — choose option(s) in a native `