screen-recording - SKILL.md Agent Skill

name: screen-recording description: Record the macOS main monitor from CLI only using tmux, ffmpeg, and sox. Use this skill when you need background start/stop recording control without MCP.

AI Builder - Screen Recording

This skill controls a macOS-only screen recorder via CLI. It records the main monitor using ffmpeg and captures audio using sox, both running in tmux sessions.

When to Use This Skill

You need to start screen recording and keep it running in the background.
You need to stop recording later and produce a final mp4 file.
You need a CLI-only flow (not MCP) for screen recording.

Your Roles in This Skill

QA Engineer: Verify recording start/stop behavior and output file correctness.
DevOps Engineer: Manage background tmux lifecycle and dependency checks.

Role Communication

As an expert in your assigned roles, you must announce your actions before performing them using the following format:

As a {Role} [and {Role}, ...], I will {action description}

This communication pattern ensures transparency and allows for human-in-the-loop oversight at key decision points.

Instructions

Follow these steps in order.

Step 1: Verify Environment

macOS only.
ffmpeg, sox, and tmux must be available in PATH.
Run commands from project root.

Step 2: Start Recording

core/bin/mac-screen-recording start

Optional arguments:

core/bin/mac-screen-recording start --fps 30 --output .skillpilot/temp/screen-recording/my-session.mp4

If ffmpeg device auto-detection fails on your machine, pass the screen device index explicitly:

core/bin/mac-screen-recording start --screen-device-index 1

Step 3: Check Status

core/bin/mac-screen-recording status

Step 4: Stop Recording

core/bin/mac-screen-recording stop

This stops tmux sessions, finalizes media, and writes the final mp4 path in output JSON.

Expected Output

start: JSON with run_id, output path, and tmux session names.
status: JSON showing whether recording is active and tmux sessions are alive.
stop: JSON with final_file path.

Key Principles

Keep one active recording at a time per state file.
Always use stop to finalize output cleanly.
Use default state path .skillpilot/temp/screen-recording/state.json unless a different workflow is required.