asg
Use this skill to convert asciinema/asciicast v3 terminal recordings into animated or static SVGs with ASG. Trigger it when a user wants to install or invoke ASG, render a .cast or .cast.zst file, cre
SKILL.mdskills/asg/SKILL.md
GitHubRender Terminal SVGs with ASG
Use ASG for asciicast v3-to-SVG work. Preserve the recording unless the user explicitly asks to trim, resize, restyle, or replace an existing output.
Workflow
1. Establish the input and output
- Accept a local
.cast, zstd-compressed.cast.zst, stdin (-), HTTP(S) URL, or asciinema.org recording ID. - Choose an explicit
.svgoutput path unless the user requests stdout. - Check before overwriting an unrelated existing file. Regenerating a named demo is an intentional overwrite.
- Let ASG validate the input instead of guessing from the extension. ASG accepts asciicast v3 only.
If ASG reports a v1 or v2 recording, migrate it first only with the user's approval:
asciinema convert old.cast recording-v3.cast
2. Choose one runner
Prefer an existing native installation after checking asg --version:
asg input.cast output.svg
If asg is unavailable and Node.js 22 or newer is available, use the npm/WASI package without installing it globally:
npx --yes @kingsword/asg@latest input.cast output.svg
For repeated use, install exactly one distribution:
npm install -g @kingsword/asg
# or
cargo install asg --locked
Use @latest for normal one-off work. Pin a package version only when the surrounding project requires reproducible tooling.
3. Render for the destination
Use window decorations for documentation and product demos:
asg input.cast output.svg --window
Render a static frame or a focused excerpt when the full recording is unnecessary:
asg input.cast still.svg --at 4.5 --window
asg input.cast excerpt.svg --from 3 --to 12 --window
Do not add --from 0.1 automatically. Add it when a README or image proxy freezes on an intentionally blank first frame, then verify that no meaningful opening content was removed.
Read the CLI reference before using non-default timing, playback, theme, font, padding, or geometry options, and when diagnosing a failed conversion.
4. Validate the result
Confirm the command exits successfully and note ASG's reported bytes, frame count, duration, and cell geometry.
Confirm the output exists, is non-empty, and parses as XML. Use
xmllint --noout output.svgwhen available; otherwise use a structured XML parser from the environment.Render or open the SVG at its intended display size. For animations, inspect the opening state and at least one later state.
For a README, reference the committed SVG by a relative path when possible:
Report the exact command, output path, conversion metrics, and validation performed.
Guardrails
- Use
--window, not--windows. - Do not hand-edit generated SVG internals; change the command or source cast and regenerate.
- Do not claim pixel-identical text across devices. SVG text uses fonts available on the viewer's system.
- Keep the SVG's aspect ratio when embedding it. Avoid rasterizing it merely to resize it.
- If identical pixels on every device matter more than vector scaling, explain that a raster renderer such as
aggis a better fit. - If a host disables SVG CSS animation, provide a static frame with
--ator use a host that serves the SVG as an image. - Treat URLs and asciinema.org IDs as network operations and respect the environment's network policy.