Record a demonstration -> create a skill

Demonstrate a task once over VNC and turn it into a reusable cua skill you can read, replay, and apply with new inputs.

Use cua skills record to demonstrate a task once in a VNC session and save it as a reusable skill. The result is ~/.cua/skills/<name>/SKILL.md plus the recorded trajectory assets, which you can inspect, replay as a video, and pass to ComputerAgent for similar tasks with new inputs. This is record-and-replay in the sense of show-once-get-a-reusable-skill, the cua analog of OpenAI Codex record-and-replay, not verbatim input playback.

Prerequisites

• Start a sandbox that exposes VNC. Use a running Cua Cloud sandbox by name, or use any VNC URL, such as a local Docker sandbox at http://localhost:8006/vnc.html.
• Install ffmpeg. The recorder fails fast if it is missing.

# macOS
brew install ffmpeg
 
# Linux
sudo apt install ffmpeg

• Set an LLM API key for captioning. The default provider is anthropic, which reads ANTHROPIC_API_KEY and uses claude-haiku-4-5 by default.

export ANTHROPIC_API_KEY=...

Use --provider openai to read OPENAI_API_KEY and use gpt-4o-mini by default. You can also pass --api-key directly.

Steps

1. Start recording.

   Use exactly one target flag: --sandbox or --vnc-url. Pass --name and --description to avoid the prompts after recording.

cua skills record \
  --sandbox my-sandbox \
  --name flight-booking \
  --description "Book a flight through the browser"

cua skills record \
  --vnc-url http://localhost:8006/vnc.html \
  --name flight-booking \
  --description "Book a flight through the browser"

The full command shape is:

cua skills record [--sandbox NAME | --vnc-url URL] [--name NAME] [--description DESC] [--provider anthropic|openai] [--model NAME] [--api-key KEY]

Short flags are -s for --sandbox, -u for --vnc-url, -n for --name, -d for --description, -p for --provider, -m for --model, and -k for --api-key.

1. Perform the task by hand in the VNC window.

   The CLI starts a local recording server, opens the VNC viewer in your browser with recording already enabled, and prints:

Recording will start automatically when you connect.

Complete the task manually in the VNC window. The recording has a 30 minute timeout.

1. Stop recording.

   Click Stop Recording in the VNC panel. If you did not pass --name or --description, enter them when prompted. Skill names can contain only letters, numbers, hyphens, and underscores.

2. Inspect the skill.

   After you stop recording, the CLI extracts frames at each input event, captions each step with the VLM, and writes the skill to ~/.cua/skills/<name>/.

cua skills read flight-booking
cua skills replay flight-booking

cua skills read prints SKILL.md as markdown by default. Use --format json when you need trajectory data and skill_prompt.

cua skills read flight-booking --format json

cua skills replay opens the recorded .mp4 in your browser. It does not replay the original inputs.

The skill directory contains:

~/.cua/skills/flight-booking/
  SKILL.md
  trajectory/
    *.mp4
    events.json
    trajectory.json
    step_N_full.jpg

SKILL.md contains YAML frontmatter with name and description, a Steps section, and an Agent Prompt section.

1. Apply the skill to a new task.

   Read SKILL.md, prefix it as context to a ComputerAgent run, then provide the real task with different inputs. The agent follows the demonstrated workflow pattern and adapts the parameters.

from pathlib import Path
from cua import ComputerAgent
 
skill_prompt = (Path.home() / '.cua/skills/flight-booking/SKILL.md').read_text()
agent = ComputerAgent(loop='anthropic')
messages = [
    {'role': 'user', 'content': skill_prompt},
    {'role': 'user', 'content': 'Book a flight from Boston to Chicago for next Friday'},
]
async for result in agent.run(messages):
    print(result)

Manage your skills

cua skills list
cua skills ls
cua skills read flight-booking
cua skills delete flight-booking
cua skills clean

cua skills clean deletes all skills after confirmation.