jamdotdev/skills

record-terminal-proof

Record a terminal run with asciinema and render it to a GIF that plays inline on GitHub, plus an MP4 when one is needed.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/jamdotdev/skills --skill record-terminal-proof

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Record terminal proof

When to use

  • The proof is terminal output: a CLI run, a migration, a test or build command.
  • The command needs no input. --command records it without an interactive shell.
  • Not for anything with a UI. Record the browser instead.

Install

bash
brew install asciinema agg      # macOS; tested with asciinema 3.2.1, agg 1.9.0

On Linux, take asciinema from the package manager and agg from its GitHub releases or cargo install --git https://github.com/asciinema/agg. asciinema does not run on Windows itself; use WSL there.

Write the script

Put the steps in a script so the recording has no typing and no pauses while you think. Echo each command before it runs, so the reader sees what ran, and sleep between steps so each result stays on screen:

bash
#!/usr/bin/env bash
set -e
step() { printf '\n\033[1m$ %s\033[0m\n' "$*"; "$@"; sleep 2; }
step npm run migrate
step npm test -- users.spec.ts

set -e stops the recording at the first failing step, so the proof cannot show success after a failure, and --return (below) makes asciinema exit with the script's status: stop and report when it is not 0. Keep secrets out of the output: no env, no tokens in arguments.

Record

bash
asciinema rec --quiet --overwrite --return --window-size 100x30 --command "bash ./demo.sh" proof.cast

With no TTY (an agent's shell), asciinema switches to headless mode by itself. A 15 s script gives a cast of about 1 KB. The cast is plain JSON lines, so keep it when someone needs the exact text.

Render

bash
agg --quiet proof.cast proof.gif

Defaults are fine for a PR: font size 16, 30 fps cap, idle gaps cut to 5 s, a 3 s hold on the last frame. 100x30 renders to about 1004x694 px; a 15 s run gives a GIF of about 50 KB in under a second.

For a slide or a social post, record at --window-size 96x24 and render with --theme github-dark --font-size 20 --idle-time-limit 2: about 1206x700 px, close to 16:9, text readable on a phone, and no long waits while a slow step runs.

Open the GIF's last frame before you share it. If it does not show the final result, the script exited early or the window is too small.

Attach to the PR

Drag the GIF into the PR description or a comment. GitHub renders it inline (images up to 10 MB).

MP4

For a tool that takes video but not GIF, convert it. tpad keeps agg's hold on the last frame, which a plain conversion drops:

bash
ffmpeg -v error -y -i proof.gif -movflags faststart -pix_fmt yuv420p \
  -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2,tpad=stop_mode=clone:stop_duration=3" proof.mp4

With Jam: when command -v jam (where jam on Windows) finds the CLI, ask the user once whether to upload the MP4; it becomes one link to comment on, with frames the next agent can read. A terminal recording has no console or network data, so the link holds the video only. Upload only on a yes, with jam create jam '{"kind": "video", "url": "", "videoPath": "proof.mp4", "screenDimensions": {"width": 1004, "height": 694}}' (the GIF's pixel size). Exit code 3 means signed out: run jam auth login, then retry.

from this repository

More skills

All skills
jamdotdev
Community

add-voiceover

Add a spoken voiceover to a video: write the script for the ear, voice it line by line with ElevenLabs, Kokoro (a free local model) or your own text-to-speech command, and lay each line under the moment it describes, with a subtitle file. Use when the user asks to add narration, a voiceover, a voice or text-to-speech to a screen recording, demo video or walkthrough, to re-voice a video with another voice, or asks why a generated voiceover sounds robotic, echoes or drifts out of sync.

1h installs
2
GitHub stars
12
Updated
Nov 18
jamdotdev
Community

jam

Route a Jam (a jam.dev screen recording or screenshot with the console, network and user actions attached) to the right Jam skill. Use when the user shares a jam.dev link with no clear ask ("look at this jam", a bare link), or types /jam. For a clear ask (fix, test, ticket, record, annotate), use that skill directly.

1h installs
2
GitHub stars
12
Updated
Nov 18
jamdotdev
Community

jam-annotate

Turn a screenshot into a Jam (a shareable jam.dev screenshot with context attached) that points at the problem, with boxes, arrows, notes, redactions and blurs drawn by jam create jam. Use when the user asks to file or share an annotated screenshot as a Jam. Local annotation or redaction requests alone do not call for this skill.

1h installs
2
GitHub stars
12
Updated
Nov 18
jamdotdev
Community

jam-fix

Find the root cause of a bug from a Jam (a jam.dev screen recording with the console, network and user actions attached), and fix it when the user asks. Without that ask it diagnoses only, with no code changes. Read the recording's diagnostics and visual evidence, then return a diagnosis with evidence. Use when the user pastes a jam.dev link or Jam id and asks to fix, debug, triage or investigate it, or asks what went wrong in a recording.

1h installs
2
GitHub stars
12
Updated
Nov 18