ScreenCI Video and Guide Skill

Use this skill when the task is about ScreenCI video recording workflows in an existing project, or updating

.video.ts

files and

screenci.config.ts

Trigger this skill when the user asks to:

create a video
show a flow as a video
create a guide/demo video

Routing rules:

If the user provides a URL, always use the
```
playwright-cli
```
skill first to inspect the real page flow and selectors before editing the ScreenCI script.
If the user provides source code for the target page/component, that usually means browser exploration is not required first.
If the request is only about application/source-code changes (not recording or
```
.video.ts
```
updates), do not use this skill.

Quick Start

Assume the project is already initialized. Add or edit video scripts in

videos/

If you are creating new videos, remove the starter

videos/example.video.ts

file.

bash

# iterate locally without recording
npx screenci test --ui

# verify repeatedly until green
npx screenci test

# only record after tests pass
npx screenci record

What ScreenCI Adds

ScreenCI uses Playwright-style

.video.ts

files and adds recording-specific helpers:

```
video()
```
declares one output video per test.
```
hide()
```
removes setup and loading sections from the final recording.
```
autoZoom()
```
follows a larger form or page area with smooth camera motion. Use it sparingly, and start with its default options unless the user explicitly asks for different zoom behavior or the flow clearly needs a targeted override.
```
createNarration()
```
is mandatory for every video: define it in every
```
.video.ts
```
file and include spoken narration throughout the demo. The opening narration should first state the purpose of the video, then continue with the explanation or walkthrough. Define the map once, then call
```
await narration.key.start()
```
where each line should begin. Use
```
await narration.key.finish()
```
only when the next action must wait for audio to finish.
Narration text can include inline speech-control tags such as
```
[pronounce: screen see eye]
```
,
```
[short pause]
```
,
```
[medium pause]
```
, and
```
[long pause]
```
when a word needs guided pronunciation or an intentional pause.

Required Conventions

Every video MUST follow these conventions:

Narration on every video (required, no exceptions) — always define
```
createNarration({ ... })
```
and add narration to every
```
.video.ts
```
file. Videos without narration are not acceptable.
Open with the video's purpose — the first spoken narration should clearly state what the video is for before moving into the step-by-step explanation.
Start on the requested page — the visible video should always begin on the page the user requested.
Hide initial setup — the initial page load should almost always be wrapped in
```
hide()
```
. Keep authentication, navigation to the starting page, loading spinners, cookie banner dismissal, and any other non-demo boilerplate inside that hidden block so they are cut from the final recording.
Navigate visibly with clicks — after hidden setup, move through the demo by clicking real links and buttons instead of calling
```
page.goto()
```
.
Use autoZoom sparingly on large page areas — add
```
autoZoom()
```
only for larger sections that benefit from camera guidance (e.g. a full form, a full dialog, or a broad list area). Keep usage sparse, and make sure each
```
autoZoom()
```
block includes multiple related interactions (typing, selecting, toggling, confirming, etc.), not just a single click.
End autoZoom before page changes — it is better to let an
```
autoZoom()
```
block finish before a navigation/page change. Staying zoomed during navigation is confusing. Start a new
```
autoZoom()
```
block on the next page/section when needed.
Prefer default action options — for
```
autoZoom()
```
and locator actions such as
```
click()
```
,
```
fill()
```
,
```
pressSequentially()
```
,
```
check()
```
,
```
uncheck()
```
,
```
selectOption()
```
,
```
selectText()
```
, and similar helpers, start with ScreenCI's default options. Do not add custom
```
zoom
```
,
```
click
```
,
```
position
```
, timing, or other locator-action overrides unless the user asks for them or the recording flow clearly needs a specific adjustment.

Command Notes

```
screenci record
```
runs the recording flow with local Playwright.
```
screenci test --ui
```
runs Playwright in UI mode for fast iteration without screen capture.
```
screenci retry
```
uploads the latest
```
.screenci
```
output when API configuration is available.

Recording Workflow

Start from the existing initialized ScreenCI package.
Add or edit
```
.video.ts
```
files in
```
videos/
```
. Remove
```
videos/example.video.ts
```
if you are creating new videos and do not need the starter video. For narration, define
```
const narration = createNarration({ ... })
```
near the top of the file and trigger lines with
```
await narration.someKey.start()
```
inside the test body. Make the first narration line state the video's purpose, then use the following lines for the explanation. Use inline tags like
```
[pronounce: ...]
```
and
```
[short pause]
```
inside cue text when needed.
Run
```
npx screenci test --ui
```
to validate selectors and flow.
Run
```
npx screenci test
```
until it passes.

Run

npx screenci record

to produce

.screenci/<video-name>/recording.mp4

and

data.json

Specific Tasks

Recording videos references/record.md

screenci

NPX Install

Tags

SKILL.md Content