record-terminal-proof skill
✓ VerifiedRecord terminal command executions and convert them into GIFs or MP4s for documentation and pull request attachments.
- GitHub stars
- 11
- Files
- 2
- Last commit
- Nov 9, 2026
- License
- MIT
- Allowed tools
- —
What does the record-terminal-proof skill do?
record-terminal-proof is an agent skill. Record terminal command executions and convert them into GIFs or MP4s for documentation and pull request attachments.
Summary generated from the skill's SKILL.md.
About the record-terminal-proof skill
Creating visual documentation for command line executions is what this skill enables for developers and technical writers. When an agent needs to provide terminal proof of a migration, build, or test command, it uses this toolset to capture the session and transform it into a shareable format. It relies on asciinema to record the session as a JSON-based cast file and agg to render that file into a GIF or MP4.
An agent should load this skill when a user requests a recording of a CLI run or needs a visual attachment for a pull request. The process involves running a script to ensure smooth playback without typing pauses, recording the output via asciinema, and then using agg or ffmpeg to generate the final media. This approach produces lightweight GIFs that render inline on GitHub or MP4 files for video-compatible platforms. It is specifically designed for text-based terminal output rather than graphical user interfaces.
What an agent can do with it
- 1Creating social media clipsRender a high-resolution terminal recording optimized for mobile viewing and social posts.
- 2Providing video for specific toolsConvert a terminal GIF into an MP4 file for tools that require video input.
- 3Uploading video linksUpload a recorded MP4 to a hosting service to provide a single link for comments.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the record-terminal-proof skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the record-terminal-proof skill in Plugin
/plugin marketplace add jamdotdev/skills /plugin install jam@jam-plugins
Install the record-terminal-proof skill in Claude Code
~/.claude/skills/record-terminal-proof/SKILL.md
$ npx degit jamdotdev/skills/skills/record-terminal-proof ~/.claude/skills/record-terminal-proofInstall the record-terminal-proof skill in Claude Code (project)
.claude/skills/record-terminal-proof/SKILL.md
$ npx degit jamdotdev/skills/skills/record-terminal-proof .claude/skills/record-terminal-proofInstall the record-terminal-proof skill in Codex
~/.agents/skills/record-terminal-proof/SKILL.md
$ npx degit jamdotdev/skills/skills/record-terminal-proof ~/.agents/skills/record-terminal-proofInstall the record-terminal-proof skill in Gemini CLI
~/.gemini/skills/record-terminal-proof/SKILL.md
$ npx degit jamdotdev/skills/skills/record-terminal-proof ~/.gemini/skills/record-terminal-proofInstall the record-terminal-proof skill in Claude.ai
npx degit jamdotdev/skills/skills/record-terminal-proof record-terminal-proof && zip -r record-terminal-proof.zip record-terminal-proof # claude.ai → Customize → Skills → + → Create skill → Upload a skill → record-terminal-proof.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablejamdotdev/skills/skills/record-terminal-proof is public and reachablegithub.com/jamdotdev/skills/tree/HEAD/skills/record-terminal ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-09github.com/jamdotdev/skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/jamdotdev/skills/blob/HEAD/skills/record-terminal ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/jamdotdev/skills/blob/HEAD/skills/record-terminal ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 70 linesgithub.com/jamdotdev/skills/blob/HEAD/skills/record-terminal ↗Pass
SKILL.md
View on GitHubRecord 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.
--commandrecords it without an interactive shell. - Not for anything with a UI. Record the browser instead.
Install
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:
#!/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
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
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:
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.
Files in this skill
2record-terminal-proof skill questions
How do I install the record-terminal-proof skill in Claude Code?
Run npx degit jamdotdev/skills/skills/record-terminal-proof ~/.claude/skills/record-terminal-proof. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the record-terminal-proof skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What should I do if the GIF does not show the final result?
If the final result is missing, it is likely because the script exited early or the window size was too small.
How can I convert the terminal recording to an MP4 while keeping the last frame visible?
Use ffmpeg with the tpad filter to clone the last frame, which prevents the video from dropping the final state.