terrylica /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
fileprovided → skip Phase 1 (file selection) - If options provided → skip Phase 2 (options)
- If
-oprovided → skip Phase 3 (output location) - If
--analyzeprovided → skip Phase 6 and auto-run analyze
Batch Mode Skip Logic
- If
--batchprovided → skip Phases 1-3, enter batch phases (7-10) - If
--sourceprovided → skip Phase 7 (source selection) - If
--output-dirprovided → skip Phase 8 (output organization)
Single File Workflow
- Preflight: Check asciinema convert command
- Discovery: Find .cast files
- Selection: AskUserQuestion for file
- Options: AskUserQuestion for conversion options
- Location: AskUserQuestion for output location
- Execute: Run asciinema convert
- Report: Display compression ratio
- Next: AskUserQuestion for follow-up action
Batch Workflow
- Preflight: Check asciinema convert command
- Source: AskUserQuestion for source directory
- Output: AskUserQuestion for output directory
- Execute: Batch convert with progress reporting
- Report: Display aggregate compression stats
- 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:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- 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.