Record Browser GIF

Every GUI pull request includes a GIF

Keep recording separate from publication

• Recording produces frame images and one local

  .gif

  artifact only; it never mutates remote state.
• Publication — pushing the GIF to an assets branch and embedding it in a pull request body — is the separate final step, performed only when the task includes attaching the GIF to a pull request. It never touches the pull request's own branch.
• Preserve the requested recording conditions. A real-server or real-credential demo must not use fixture queries, mock transports, synthetic event injection, or test-only hooks. If credentials or the server are unavailable, report that limitation instead of substituting a fixture.
• Never read or expose credential values. Use the application's normal configuration path and a benign demonstration prompt.

Stage the application

1. Require a clean worktree, record its exact commit with

   git rev-parse HEAD

   , then build that recorded tree with the repository's build commands for the recorded tree. A GIF recorded against another commit's build misattributes the evidence.
2. Boot one server per port from that tree with the application's fresh state roots, workspace, and session state. Give the browser a fresh isolated context or profile as well; if the browser workflow cannot create one, clear that origin's cookies and site storage before navigation so persisted client state cannot affect the evidence. Source credentials through the application's normal configuration path; never echo them.
3. Treat one storyboard as one evidence run: every published frame comes from that server and those state roots, workspace, session, and data-flow scenario run. If capture automation fails, discard its frames and rerun from fresh roots; never splice frames from separate runs.
4. When switching between pull requests, stop the old server by PID or an exact match on its command line. A broad

   pkill -f

   pattern can match and kill the shell that launched it — including your own.

Record the flow

1. Invoke the repository's browser-control skill when available, and follow its setup, interaction, and cleanup instructions. Use the user's existing browser state only when requested or required; state that exception in the provenance and do not claim fresh client state. If browser control is unavailable, use the repository-declared Playwright dependency in an isolated headless browser; do not install another driver or launch the user's browser. State that fallback in the provenance.
2. Before recording, identify the exact origin, whether the app is built or in development, the transport, and any fixture or mock mode. Record only claims that the observed setup supports.
3. When a production default opens a native operating-system surface that headless automation cannot drive, select an official browser-operable production backend through the application's normal configuration. State the override in the provenance; a fixture, mock transport, or test-only hook is not an acceptable substitute.
4. Choose three to six states that tell one story, such as typed, running, settled, and detail. Prefer semantic state changes over continuous capture; omit loading churn that does not help the viewer.
5. Keep one viewport and crop for every frame, and name frames lexically:

   00-initial.png

   ,

   01-typed.png

   , and so on.
6. Store frames under the repository's gitignored browser-tool screenshots directory (for example

   .playwright-mcp/

   ), since browser-tool screenshots can only be written under the tool's allowed roots and relative filenames resolve against the repository root. Create the frame subdirectory first (

   mkdir -p <screenshots-dir>/gif-frames-<label>

   ); writing into a missing directory fails with ENOENT at capture time.
7. Before each screenshot, wait for a concrete UI condition such as a unique label, enabled control, changed document title, or completed response. Require the locator to resolve exactly one element; for Playwright accessible-name locators, use

   exact: true

   when equality is intended because descendant text or a prompt echo can otherwise create a false match. Do not use a fixed delay as proof that the application reached the state.
8. Make completion predicates match an exact-text element — for example, an element whose trimmed text equals the expected reply — never a substring check such as

   body.textContent.includes(...)

   , which the echo of the user's own prompt also satisfies.
9. When the claim involves a tool call, rejection, or recovery, include a detail or trajectory frame that shows the tool identity, status or stable error code, and the downstream result. A chat-only outcome does not prove why the tool path behaved that way.
10. Capture a transient state (spinner, running row) by driving a slow foreground operation — for example, a

    sleep 15

    bash command — and polling a concrete DOM marker (a

    data-*

    attribute) inside one browser-script call that also takes the screenshot. State polled across separate tool calls is lost, because the turn settles between calls.
11. Engineer the prompt so the state you need actually occurs: instruct the model to wait in the foreground when it would otherwise background a slow command, and give it a settle sentinel such as "reply with the single word done" to anchor the completion predicate.
12. Capture no secrets, personal data, unrelated tabs, or transient notifications. Stop any unnecessarily long real-server run after the demonstrated state is visible.

Encode the GIF

python3

ffmpeg

ffprobe

GIF_SKILL_DIR

GIF_SKILL_DIR=... python3 "$GIF_SKILL_DIR/..."

export GIF_SKILL_DIR=/absolute/path/to/this/skill
python3 "$GIF_SKILL_DIR/scripts/encode_gif.py" \
  /absolute/path/to/frames \
  /absolute/path/to/demo.gif \
  --durations 1.5,1.5,1.5,3.5 \
  --fps 10 \
  --max-width 1200 \
  --colors 128

--max-bytes

--max-width

--colors

--fps

--force

Verify the artifact

1. Read the encoder's JSON summary and confirm the output path, source and encoded frame counts, dimensions, duration, and byte size.
2. Visually read the encoded GIF itself, not only the source frames. Confirm that the transition is legible, the last state is held long enough, and no sensitive content appears. If the viewer renders only the first frame, decode representative frames from the encoded GIF with

   ffmpeg

   and inspect those; the pre-encode screenshots do not prove the encoded order, palette, or final hold.
3. Run

   git status --short

   and confirm frames and the artifact landed only under ignored paths.
4. Return the absolute GIF path, render it when the client supports local media, and state whether the recording used a real server, fixture, or another transport. When the task does not include attaching the GIF to a pull request, stop here.

Publish to an assets branch

<series>-assets

git ls-remote --heads origin '*assets*'

git clone --branch <assets-branch> --single-branch --depth 1 <repo-url> /tmp/assets-checkout
cp /absolute/path/to/demo.gif /tmp/assets-checkout/<name>.gif
cd /tmp/assets-checkout
git add <name>.gif
git commit -m "assets: <what it shows> gif (#<pr>)"
git push origin <assets-branch>

git clone --depth 1 <repo-url> /tmp/assets-checkout

git switch --orphan <assets-branch>

200

image/gif

404

<img>

?raw=true

![<alt text>](https://github.com/<owner>/<repo>/blob/<assets-branch>/<name>.gif?raw=true)