vhs

name	vhs
description	VHS terminal recording best practices from Charmbracelet (formerly charmbracelet-vhs). This skill should be used when writing, reviewing, or editing VHS tape files to create professional terminal GIFs and videos. Triggers on tasks involving .tape files, VHS configuration, terminal recording, demo creation, or CLI documentation.

Charmbracelet VHS Best Practices

Comprehensive best practices guide for VHS terminal recordings, maintained by Charmbracelet. Contains 47 rules across 8 categories, prioritized by impact to guide creation of professional, portable, and optimized terminal demos.

When to Apply

Reference these guidelines when:

• Writing new VHS tape files
• Creating terminal demos for documentation
• Setting up CI/CD for automated GIF generation
• Optimizing recording file size and quality
• Troubleshooting tape file issues
• Reviewing tape files for best practices

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Configuration Structure	CRITICAL	config-
2	Dependency Management	CRITICAL	deps-
3	Command Syntax	HIGH	cmd-
4	Timing & Synchronization	HIGH	timing-
5	Output Optimization	MEDIUM-HIGH	output-
6	Visual Quality	MEDIUM	visual-
7	CI/Automation	MEDIUM	ci-
8	Advanced Patterns	LOW	advanced-

Quick Reference

1. Configuration Structure (CRITICAL)

• config-settings-order - Place all settings before commands
• config-output-first - Declare output at file start
• config-shell-explicit - Explicitly set shell type
• config-typing-speed-global - Set global TypingSpeed early
• config-dimensions-explicit - Set explicit terminal dimensions
• config-comments-document - Use comments to document tape structure

2. Dependency Management (CRITICAL)

• deps-require-early - Use Require for dependency validation
• deps-require-order - Place Require before settings
• deps-require-all - Require all external commands
• deps-system-requirements - Verify system dependencies

3. Command Syntax (HIGH)

• cmd-type-syntax - Use correct Type command syntax
• cmd-enter-explicit - Always follow Type with Enter
• cmd-key-repeat - Use key repeat counts
• cmd-ctrl-combinations - Use Ctrl combinations for terminal control
• cmd-hide-show - Use Hide/Show for sensitive operations
• cmd-env-variables - Use Env for environment variables
• cmd-screenshot - Use Screenshot for static captures
• cmd-multiline-type - Handle multiline commands properly

4. Timing & Synchronization (HIGH)

• timing-sleep-after-enter - Add Sleep after commands for output
• timing-wait-pattern - Use Wait for dynamic command completion
• timing-type-speed-override - Override TypingSpeed for emphasis
• timing-sleep-units - Use explicit time units
• timing-final-sleep - End recordings with final Sleep
• timing-natural-pauses - Add natural pauses between actions
• timing-wait-timeout - Set appropriate Wait timeouts
• timing-playback-speed - Use PlaybackSpeed for final adjustments

5. Output Optimization (MEDIUM-HIGH)

• output-format-selection - Choose output format based on use case
• output-framerate - Optimize framerate for file size
• output-dimensions-optimize - Right-size terminal dimensions
• output-loop-offset - Use LoopOffset for seamless loops
• output-multiple-formats - Generate multiple output formats
• output-relative-paths - Use relative paths for portability

6. Visual Quality (MEDIUM)

• visual-font-readable - Choose readable font settings
• visual-theme-selection - Select appropriate theme
• visual-window-decoration - Add window decorations for polish
• visual-spacing - Adjust letter and line spacing
• visual-padding-margin - Use padding and margins effectively
• visual-cursor-visibility - Ensure cursor visibility

7. CI/Automation (MEDIUM)

• ci-github-action - Use official VHS GitHub Action
• ci-auto-commit - Auto-commit generated assets
• ci-golden-files - Use golden files for integration testing
• ci-matrix-builds - Generate platform-specific demos
• ci-caching - Cache VHS dependencies in CI

8. Advanced Patterns (LOW)

• advanced-source-include - Use Source for reusable tape components
• advanced-clipboard - Use Copy and Paste for complex input
• advanced-recording-live - Record live sessions then edit
• advanced-server-mode - Use server mode for remote access

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files

File	Description
AGENTS.md	Complete compiled guide with all rules
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information