runcast-setup
/runcast-setup
Sets up Runcast in a web app project, or refreshes it — installs the kit, studies the app's code (routes, forms, labels, sign-in, start-up state, brand) and writes the project's recording.config.ts, login helper and step, a login scenario and PROJECT.md (screen map, known forms, selectors, known behaviours, helper and step catalogs), then verifies it with a test run. Use when someone adds Runcast to a project, says "set up recordings / demo videos / e2e recordings for this app", when PROJECT.md is missing or stale, or when the login or app structure changed.
- Author
- datafloem ↗
- Repository
- runcast ↗
- Licence
- MIT
- Last repository change
- 10.11.2026
Assessment and security
- Files in this package
- 108
- Scripts
- 76
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 76 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: kit/cli.ts, kit/core/capture-log.ts, kit/core/cursor.ts, kit/core/env.ts, kit/core/file-viewer.ts, kit/core/format.ts, kit/core/index.ts, kit/core/mode.ts, kit/core/narration.ts, kit/core/native-ui.ts, kit/core/on-screen.ts, kit/core/permissions.ts, kit/core/playwright.ts, kit/core/project.ts, kit/core/recorder.ts, kit/core/runtimes.ts, kit/core/scenario.ts, kit/core/scene-contract.ts, kit/core/sc
What it does and when to use it
Sets up Runcast in a web app project, or refreshes it — installs the kit, studies the app's code (routes, forms, labels, sign-in, start-up state, brand) and writes the project's recording.config.ts, login helper and step, a login scenario and PROJECT.md (screen map, known forms, selectors, known behaviours, helper and step catalogs), then verifies it with a test run. Use when someone adds Runcast to a project, says "set up recordings / demo videos / e2e recordings for this app", when PROJECT.md is missing or stale, or when the login or app structure changed.
Original author description
Sets up Runcast in a web app project, or refreshes it — installs the kit, studies the app's code (routes, forms, labels, sign-in, start-up state, brand) and writes the project's recording.config.ts, login helper and step, a login scenario and PROJECT.md (screen map, known forms, selectors, known behaviours, helper and step catalogs), then verifies it with a test run. Use when someone adds Runcast to a project, says "set up recordings / demo videos / e2e recordings for this app", when PROJECT.md is missing or stale, or when the login or app structure changed.
How it works
- 1. Install
- 2. Study the app
- 3. Write the project layer
- 4. Verify
- 5. Hand over
- Keeping it current
SKILL.md preview
---
name: runcast-setup
description: Sets up Runcast in a web app project, or refreshes it — installs the kit, studies the app's code (routes, forms, labels, sign-in, start-up state, brand) and writes the project's recording.config.ts, login helper and step, a login scenario and PROJECT.md (screen map, known forms, selectors, known behaviours, helper and step catalogs), then verifies it with a test run. Use when someone adds Runcast to a project, says "set up recordings / demo videos / e2e recordings for this app", when PROJECT.md is missing or stale, or when the login or app structure changed.
---
# Setting up Runcast in a project
Runcast is app-agnostic: it records Playwright flows into demo
videos and runs them as tests. It comes as a plugin (Claude Code, Codex,
Antigravity) or as a copied folder (other tools); either way its runtime (the kit plus Playwright
and canvas) lives in a shared cache, not in the project. Each app
adds a **recording folder** (default `tests/recording/`) with what is specific
to it. This skill creates and maintains that folder. When it is done, the
`runcast-plan` and `runcast-scenario` skills can work on the app.
Talk with the user in their language; write code, comments and `PROJECT.md`
in English.
## 1. Install
1. **Find the kit's CLI**, `kit/cli.ts`:
- as a plugin (Claude Code, Codex, Antigravity): in this skill's own folder,
next to this `SKILL.md` (`<skill folder>/kit/cli.ts`); in Claude Code also
`${CLAUDE_PLUGIN_ROOT}/skills/runcast-setup/kit/cli.ts`;
- as a copied folder: wherever the user put the plugin (e.g.
`tools/runcast/skills/runcast-setup/kit/cli.ts`); if there is
none, ask the user to install the plugin or say where to copy it from;
- in a project already set up: `<recording folder>/.kit/cli.ts` (skills
copied with `--skills` have no `kit/` folder; use this one).
2. **Run setup** from the project root (it changes nothing outside the
recording folder and the shared cache):
`node <kit>/cli.ts setup --dir <recording folder> --name "<App>" --base-url <url>`.
Ask only for what you cannot find: the recording folder (suggest
`tests/recording`) and, if the dev URL is not in the code, the URL.
- The first run builds the runtime in `~/.cache/runcast/` and
installs Playwright and canvas there (a few hundred MB, once per kit
version). Tell the user before running it.
- It creates the recording folder from templates (existing files are
kept), links `<recording folder>/.kit` to the runtime and adds `.kit` to
the folder's `.gitignore`.
- Without the plugin (copied folder), add
`--skills .claude/skills,.agents/skills` so the user's AI tools find the
skills.
3. **Doctor:** setup ends with `doctor` (also
`node <recording folder>/.kit/cli.ts doctor`): Node 22.18+, ffmpeg (video,
narration; Windows: `winget install Gyan.FFmpeg`), Xvfb on Linux without a
screen (only for `REC_CAPTURE=screen`), Google Chrome (or
`REC_CHANNEL=chromium`), `.env.local`. Ask before installing anything
system-wide.
Run setup again after a kit update, or when `.kit` is missing (a fresh clone):
it relinks the runtime and never overwrites the project's own files.
## 2. Study the app
Read the code; ask the user only for what the code cannot tell. Note what you
find, it becomes `PROJECT.md`:
- **Stack and run:** framework, router, UI and form libraries; the dev command
and URL (package.json scripts, the bundler config); how the backend is
reached (proxy, mock server, VPN...).
- **Routes:** the route table or path constants → the screen map: areas, the
records they hold, list pages and add/edit pages. Which screens need an
admin.
- **Labels:** where UI texts live (i18n files) and in which locale tests should
run; scenarios find controls by those labels.
- **Selectors:** what stable hooks the app has (`data-testid`, field `name`s,
its own attributes, link targets).
- **Forms:** how a page leads to its form component, its fields, the
validation schema (required fields, limits), and where saving navigates.
Describe this as a method (section "Finding a screen's form"), plus a table
of the forms planned scenarios will need.
- **Sign-in:** the login path, fields, submit button, where it lands after
sign-in, SSO or extra steps. Never ask for a password in the chat: the user
writes it to `.env.local`.
- **Start-up state:** what the app reads on start from localStorage, cookies
or the system (theme, language, onboarding flags, banners). Seed what makes
videos consistent through `localStorage` / `colorScheme` in
`recording.config.ts`; ask the user which theme the videos should use.
- **Mobile layout:** whether the app has a narrow-screen layout, for vertical
videos (Shorts, Reels). Signs of one: a viewport meta tag, `max-width` /
`min-width` media queries or responsive classes (Tailwind `sm:` / `md:`, a
UI library's breakpoint props) on the main layout, a mobile menu or
drawer component. Signs against: a fixed `min-width` on the page, wide
tables and sidebars without breakpoints, a note that only desktop is
supported. Write the verdict with its evidence: "yes", "partly" (which
screens) or "no". If a scenario exists, a `REC_FORMAT=vertical` test run
shows whether the flow still works at 540×960.
- **Brand:** the accent colour and a logo file for the title cards (look in
`public/`, assets, the theme or CSS variables). Confirm with the user.
- **Quirks:** pagination, lazy-loaded lists, redirects after saving, slow first
loads, menus that start collapsed... Add each to "Known behaviours" as you
find it.
## 3. Write the project layer
- `recording.config.ts`: `name`, `baseURL` (from a setting with a default),
`locale`, `localStorage`, `colorScheme`, `brand`.
- `helpers/auth.ts`: `openLogin` and `login` with confirmed selectors; solve
sign-in quirks there.
- `steps/auth.ts`: the `login` step (reads the account settings; rename
`APP_USERNAME` / `APP_PASSWORD` if the project prefers its own prefix, in
`.env.example` too).
- `scenarios/login.spec.ts`: the login scenario, the setup's smoke test.
- `PROJECT.md`: fill every TODO section from step 2. Keep it factual and
short; tables over prose. Helper and step catalogs list what exists.
- `AGENTS.md`: the template is generic; add the project's own rules if any
(e.g. "the backend needs the VPN").
- `.env.example`: every setting the project uses, with a comment.
- If the project lints or typechecks its folders, make sure the recording
folder and the kit are covered (or excluded on purpose).
## 4. Verify
1. Typecheck: the project's own TypeScript if it has one
(`npx tsc -p <recording folder> --noEmit`), otherwise
`npx --yes -p typescript@5 tsc -p <recording folder> --noEmit` (the project
needs no TypeScript of its own). Run the project's linter and formatter on
the new files.
2. `node <recording folder>/.kit/cli.ts test --list` lists the login scenario.
3. Ask the user to put the account in `.env.local` and to start the app,
then run `node <recording folder>/.kit/cli.ts test login`. Fix selectors until it passes.
4. Offer a short video check: `node <recording folder>/.kit/cli.ts video login --render`
(needs ffmpeg; it records a headless Chrome tab, so nothing opens and the
user can keep working; with `REC_CAPTURE=screen` macOS needs Screen
Recording permission, Linux xvfb without a screen, Windows an unlocked
desktop). On Windows, use PowerShell equivalents for shell commands (for
example `Copy-Item` instead of `cp`). Look at
a frame of `videos/login.mp4` (e.g. with ffmpeg) to check theme and brand.
## 5. Hand over
Tell the user what was created and what remains (TODOs, missing helpers), and
that new videos start with the `runcast-plan` skill ("plan a new
demo video").
## Keeping it current
Run this skill again when the app's sign-in, routes or start-up state change,
or when `PROJECT.md` no longer matches the code: update the affected sections
and helpers, then repeat step 4.
Files in this package (108)
- SKILL.md 8 KB
- kit/README.md 36 KB
- kit/cli.ts 18 KB
- kit/package-lock.json 22 KB
- kit/package.json 1 KB
- kit/tsconfig.json 1 KB
- kit/core/capture-log.ts 12 KB
- kit/core/cursor.ts 1 KB
- kit/core/env.ts 1 KB
- kit/core/file-viewer.ts 2 KB
- kit/core/format.ts 2 KB
- kit/core/index.ts 1 KB
- kit/core/mode.ts 5 KB
- kit/core/narration.ts 5 KB
- kit/core/native-ui.ts 10 KB
- kit/core/on-screen.ts 2 KB
- kit/core/permissions.ts 5 KB
- kit/core/playwright.ts 6 KB
- kit/core/project.ts 4 KB
- kit/core/recorder.html 7 KB
- kit/core/recorder.ts 54 KB
- kit/core/runtimes.ts 2 KB
- kit/core/scenario.ts 16 KB
- kit/core/scene-contract.ts 4 KB
- kit/core/scene.ts 5 KB
- kit/core/tab-capture.ts 18 KB
- kit/core/video-capture.ts 14 KB
- kit/core/virtual-mouse.ts 5 KB
- kit/core/xvfb.ts 2 KB
- kit/core/stage/blank.html 1 KB
- kit/core/stage/file.html 9 KB
- kit/core/stage/files.html 8 KB
- kit/scripts/narration.ts 23 KB
- kit/scripts/scene.ts 4 KB
- kit/scripts/youtube.ts 17 KB
- kit/scripts/video/audio.ts 4 KB
- kit/scripts/video/frames.ts 6 KB
- kit/scripts/video/progress.ts 1 KB
- kit/scripts/video/render.ts 77 KB
- kit/scripts/video/run.ts 2 KB
- kit/scripts/video/scene-capture.ts 6 KB
- kit/scripts/video/scenes.ts 5 KB
- kit/scripts/video/take.ts 1 KB
- kit/scripts/video/timeline.ts 19 KB
- kit/scripts/video/timemap.ts 20 KB
- kit/scripts/video/voice-edges.ts 4 KB
- kit/templates/project/.env.example.tmpl 3 KB
- kit/templates/project/.gitignore.tmpl 1 KB
- kit/templates/project/AGENTS.md.tmpl 3 KB
- kit/templates/project/CLAUDE.md.tmpl 1 KB
- kit/templates/project/PROJECT.md.tmpl 3 KB
- kit/templates/project/README.md.tmpl 2 KB
- kit/templates/project/kit.ts.tmpl 1 KB
- kit/templates/project/package.json.tmpl 1 KB
- kit/templates/project/playwright.config.ts.tmpl 1 KB
- kit/templates/project/recording.config.ts.tmpl 1 KB
- kit/templates/project/tsconfig.json.tmpl 1 KB
- kit/templates/project/helpers/auth.ts.tmpl 1 KB
- kit/templates/project/helpers/index.ts.tmpl 1 KB
- kit/templates/project/scenarios/login.spec.ts.tmpl 1 KB
- kit/templates/project/steps/auth.ts.tmpl 1 KB
- kit/templates/project/steps/index.ts.tmpl 1 KB
- kit/test/capture-log.test.ts 3 KB
- kit/test/doctor.test.ts 2 KB
- kit/test/downloads-stage.test.ts 2 KB
- kit/test/downloads.test.ts 3 KB
- kit/test/file-viewer.test.ts 4 KB
- kit/test/files-screen.test.ts 2 KB
- kit/test/files.test.ts 8 KB
- kit/test/frames.test.ts 4 KB
- kit/test/live-pause.test.ts 4 KB
- kit/test/mode.test.ts 3 KB
- kit/test/narration-plan.test.ts 3 KB
- kit/test/narration.test.ts 1 KB
- kit/test/native-ui.test.ts 9 KB
- kit/test/on-screen.test.ts 3 KB
- kit/test/permissions.test.ts 4 KB
- kit/test/playwright-config.test.ts 1 KB
- kit/test/progress.test.ts 1 KB
- kit/test/project-types.test.ts 2 KB
- kit/test/project.test.ts 2 KB
- kit/test/recorder-steps.test.ts 4 KB
- kit/test/recorder-test-mode.test.ts 2 KB
- kit/test/render-audio.test.ts 4 KB
- kit/test/render-steps.test.ts 16 KB
- kit/test/render-sync.test.ts 6 KB
- kit/test/run-options.test.ts 1 KB
- kit/test/runtimes.test.ts 3 KB
- kit/test/scene-placeholder.test.ts 5 KB
- kit/test/scene.test.ts 3 KB
- kit/test/scenes.test.ts 3 KB
- kit/test/secrets.test.ts 4 KB
- kit/test/size-window.test.ts 2 KB
- kit/test/stage-paint.test.ts 3 KB
- kit/test/tab-capture.test.ts 17 KB
- kit/test/timeline.test.ts 2 KB
- kit/test/timemap.test.ts 14 KB
- kit/test/virtual-mouse.test.ts 2 KB
- kit/test/voice-edges.test.ts 6 KB
- kit/test/linux/Dockerfile 1 KB
- kit/test/linux/run.sh 3 KB
- kit/test/linux/selftest.narration.json 1 KB
- kit/test/linux/selftest.spec.ts.tmpl 1 KB
- kit/test/linux/serve.ts 1 KB
- kit/test/linux/site/home/index.html 1 KB
- kit/test/linux/site/login/index.html 1 KB
- kit/test/linux/site/orders/index.html 6 KB
- kit/test/linux/site/upload/index.html 2 KB
Versions
The database has no other skills named runcast-setup.
Database snapshot: 13.11.2026 · package version a04e4ad9de54 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100runcast-scenario
Writes or fixes a recording scenario with Runcast — a Playwright flow through a web app that runs as a fast end-to-end test or is recorded into a finished demo video (headless tab capture, virtual cursor, calm camera, captions, title cards, voice-over). Use when asked to add,… - 98runcast-publish
Publishes a rendered Runcast video to YouTube — checks the video, walks the user step by step through the one-time Google Cloud setup (project, YouTube Data API v3, OAuth consent screen, Desktop app client), has them sign in in their own browser, drafts the title, description,… - 100ui-walkthrough
Make a narrated video of what a merged pull request changed in a web app's UI — recordings of the real running app, before and after, with voiceover and captions — instead of reading code. Use when asked for a PR video, UI walkthrough, "what changed" video, release demo or… - 100capture-auth
This skill should be used when the user asks to "capture auth for my app", "sign into deckchecker", "save login for seatify", "add my app to playwright auth", "authenticate to my site", "set up QA user profiles", "sign in as admin", "sign in as planner", or wants to set up… - 100google-sign-in
Adds "Log in with Google" to a website or app, or fixes it when it breaks. Sets up the consent screen and the OAuth client, lists the exact redirect URLs for local and for the live site (the most common break), and wires it into Auth.js (NextAuth), Supabase Auth, Firebase Auth… - 100e2e-flow-tester
Finds a web app's critical user flows (sign up, log in, checkout, password reset, creating and editing the core object, search, settings) and writes Playwright end-to-end tests that drive a real browser through them, using the project's existing Playwright or Cypress setup when…