/asciinema-tools:convert

Convert asciinema .cast recordings to clean .txt files. Supports single file and batch directory modes.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

Arguments

Single File Mode

Argument	Description
file	Path to .cast file
-o, --output	Output path (default: same dir)
--index	Create timestamp indexed version
--chunks	Split at 30s+ idle pauses
--dims	Preserve terminal dimensions
--analyze	Auto-run /analyze after conversion

Batch Mode

Argument	Description
--batch	Enable batch mode for directory conversion
--source	Source directory (default: ~/asciinemalogs)
--output-dir	Output directory (default: ~/Downloads/cast-txt/)
--skip-existing	Skip files that already have .txt output (default: true)

Note: --batch and positional file are mutually exclusive.

Execution

Invoke the asciinema-converter skill with user-selected options.

Single File Skip Logic

• If file provided → skip Phase 1 (file selection)
• If options provided → skip Phase 2 (options)
• If -o provided → skip Phase 3 (output location)
• If --analyze provided → skip Phase 6 and auto-run analyze

Batch Mode Skip Logic

• If --batch provided → skip Phases 1-3, enter batch phases (7-10)
• If --source provided → skip Phase 7 (source selection)
• If --output-dir provided → skip Phase 8 (output organization)

Single File Workflow

1. Preflight: Check asciinema convert command
2. Discovery: Find .cast files
3. Selection: AskUserQuestion for file
4. Options: AskUserQuestion for conversion options
5. Location: AskUserQuestion for output location
6. Execute: Run asciinema convert
7. Report: Display compression ratio
8. Next: AskUserQuestion for follow-up action

Batch Workflow

1. Preflight: Check asciinema convert command
2. Source: AskUserQuestion for source directory
3. Output: AskUserQuestion for output directory
4. Execute: Batch convert with progress reporting
5. Report: Display aggregate compression stats
6. Next: AskUserQuestion for follow-up action

Examples

# Single file conversion
/asciinema-tools:convert ~/Downloads/session.cast

# Batch mode with defaults
/asciinema-tools:convert --batch

# Batch mode with custom paths
/asciinema-tools:convert --batch --source ~/Downloads --output-dir ~/cast-txt/

# Batch mode, force re-convert existing
/asciinema-tools:convert --batch --skip-existing=false

Troubleshooting

Issue	Cause	Solution
asciinema not found	asciinema not installed	brew install asciinema
Convert command failed	Corrupted .cast file	Try asciinema cat file.cast first
No .cast files found	Wrong directory	Check --source path
Output not created	Permission denied	Check write permissions on output
File too large	Long recording session	Use --chunks to split at pauses

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.