Agent-Skills.md

Agent Skills: asciinema-streaming-backup

Real-time asciinema backup to GitHub orphan branch. TRIGGERS - streaming backup, asciinema backup, session backup, recording backup.

UncategorizedID: terrylica/cc-skills/asciinema-streaming-backup

Repository

terrylica/cc-skills
terrylicaLicense: MIT
264

Install this agent skill to your local

pnpm dlx add-skill https://github.com/terrylica/cc-skills/tree/HEAD/plugins/asciinema-tools/skills/asciinema-streaming-backup

Skill Files

Browse the full folder contents for asciinema-streaming-backup.

Download Skill

Loading file tree…

plugins/asciinema-tools/skills/asciinema-streaming-backup/SKILL.md

Skill Metadata

Name
asciinema-streaming-backup
Description
Real-time asciinema backup to GitHub orphan branch. TRIGGERS - streaming backup, asciinema backup, session backup, recording backup.

asciinema-streaming-backup

Complete system for streaming asciinema recordings to GitHub with automatic brotli archival. Uses idle-detection for intelligent chunking, zstd for concatenatable streaming compression, and GitHub Actions for final brotli recompression.

When to Use This Skill

Use this skill when:

  • Setting up real-time backup of asciinema recordings to GitHub
  • Configuring idle-detection chunking for recordings
  • Creating orphan branch infrastructure for recording storage
  • Integrating GitHub Actions for brotli recompression

Platform: macOS, Linux Isolation: Uses Git orphan branch (separate history, cannot pollute main)

Architecture Overview

┌─────────────────┐     zstd chunks      ┌─────────────────┐     Actions      ┌─────────────────┐
│  asciinema rec  │ ──────────────────▶  │  GitHub Orphan  │ ───────────────▶ │  brotli archive │
│  + idle-chunker │   (concatenatable)   │  gh-recordings  │                  │  (300x compress)│
└─────────────────┘                      └─────────────────┘                  └─────────────────┘
         │                                        │
         │ Idle ≥30s triggers chunk               │ Separate history
         ▼                                        │ Cannot PR to main
    ~/asciinema_recordings/                                 ▼
    └── repo-name/                          .github/workflows/
        └── chunks/*.zst                    └── recompress.yml

Requirements

| Component | Required | Installation | Version | | ----------------- | -------- | ------------------------ | ------------- | | asciinema CLI | Yes | brew install asciinema | 3.0+ (Rust) | | zstd | Yes | brew install zstd | Any | | brotli | Yes | brew install brotli | Any | | git | Yes | Pre-installed | 2.20+ | | gh CLI | Yes | brew install gh | Any | | fswatch | Optional | brew install fswatch | For real-time |

Workflow Phases

Phase 0: Preflight Validation

Verify all tools installed, offer self-correction if missing. Run the preflight check script, then AskUserQuestion to offer installation for missing tools.

See Setup Scripts for the complete preflight-check.sh script.

Self-Correction: If tools are missing, generate installation command and offer to run it.

Phase 1: GitHub Account Detection

Detect available GitHub accounts from 5 sources (SSH config, SSH keys, gh CLI, mise env, git config) and let user choose which to use.

See Account & Repository Detection for the detection script, scoring logic, and AskUserQuestion flow.

Phase 1.5: Current Repository Detection

Detect current git repository context (CURRENT_REPO_OWNER, CURRENT_REPO_NAME, DETECTED_FROM) to provide intelligent defaults for Phase 2.

See Account & Repository Detection for the detection script.

Phase 2: Core Configuration

Gather essential configuration: repository URL (with auto-detection from Phase 1.5), recording directory, and branch name.

See Configuration Reference for all AskUserQuestion sequences and URL normalization logic.

Phase 3: Advanced Configuration

Allow customization of compression and behavior parameters:

| Parameter | Default | Range | | -------------- | ------- | ----------- | | Idle threshold | 30s | 5-300s | | zstd level | 3 | 1-22 | | Brotli level | 9 | 1-11 | | Auto-push | Yes | Yes/No | | Poll interval | 5s | 2s, 5s, 10s |

See Configuration Reference for all AskUserQuestion sequences.

Phase 4: Orphan Branch Setup

Create or configure the orphan branch with GitHub Actions workflow. Checks for existing branch first and offers clone/reset/verify options.

Key actions:

  1. Check if branch exists on remote via git ls-remote
  2. If exists: AskUserQuestion for clone/reset/verify
  3. If new: Create orphan branch, add workflow + directory structure, push

See Setup Scripts for the complete setup-orphan-branch.sh script. See GitHub Workflow for the full recompress.yml Actions workflow.

Phase 5: Local Environment Setup

Configure local directory and generate customized idle-chunker.sh with user parameters embedded from Phase 3.

Key actions:

  1. Clone orphan branch to ~/asciinema_recordings/<repo>/
  2. Generate idle-chunker.sh with embedded configuration
  3. Display configuration summary and usage instructions

See Setup Scripts for local setup scripts. See Idle Chunker for the complete chunker implementation.

Phase 6: Autonomous Validation

Claude executes 8 tests autonomously, displaying formatted results. Only 2 tests require user action (recording test, chunker live test).

| Test Category | Count | Autonomous? | | ---------------------- | ----- | ----------- | | Tool preflight | 5 | Yes | | Compression round-trip | 3 | Yes | | Repository validation | 4 | Yes | | GitHub Actions trigger | 1 | Yes | | Recording test | 1 | No (USER) | | Chunker live test | 1 | No (USER) |

See Autonomous Validation for the complete validation script, user-required test flows, and troubleshooting table.

Quick Start

First-Time Setup

/usr/bin/env bash << 'PREFLIGHT_EOF'
# 1. Check requirements
for tool in asciinema zstd brotli git gh; do
  command -v "$tool" &>/dev/null && echo "$tool: OK" || echo "$tool: MISSING"
done

# 2. Create orphan branch (replace with your repo)
REPO="git@github.com:YOUR/REPO.git"
./setup-orphan-branch.sh "$REPO"

# 3. Validate setup
./validate-setup.sh "$HOME/asciinema_recordings/REPO"
PREFLIGHT_EOF

Recording Session

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
# Terminal 1: Start recording
WORKSPACE=$(basename "$PWD")
asciinema rec $PWD/tmp/${WORKSPACE}_$(date +%Y-%m-%d_%H-%M).cast

# Terminal 2: Start idle-chunker
~/asciinema_recordings/REPO/idle-chunker.sh $PWD/tmp/${WORKSPACE}_*.cast
SKILL_SCRIPT_EOF

Key Design Decisions

| Decision | Rationale | | ----------------------- | -------------------------------------------------- | | zstd for streaming | Supports frame concatenation (brotli doesn't) | | brotli for archival | Best compression ratio (~300x for .cast files) | | Orphan branch | Complete isolation, can't pollute main history | | Idle-based chunking | Semantic breakpoints, not mid-output splits | | Shallow clone | Minimal disk usage, can't accidentally access main | | 30s idle threshold | Balances chunk frequency vs semantic completeness |

Troubleshooting

See Troubleshooting Guide for common issues and fixes.

Post-Change Checklist

After modifying this skill:

  1. [ ] Orphan branch creation scripts use heredoc wrapper
  2. [ ] All bash blocks compatible with zsh (no declare -A, no grep -P)
  3. [ ] GitHub Actions workflow validates brotli recompression
  4. [ ] Idle chunker handles both macOS and Linux stat syntax
  5. [ ] Detection flow outputs parseable key=value format
  6. [ ] References validate links to external documentation

Reference Documentation

asciinema-streaming-backup Skill | Agent Skills