Screen Record

Screen Record

Translate a user’s natural-language request into a safe invocation of the screen-record CLI.

Contract

Prereqs:

• screen-record available on PATH (install via brew install nils-cli).
• agent-out available on PATH for canonical project-scoped artifact directories (also from nils-cli).
• macOS 12+ for native capture (ScreenCaptureKit + AVFoundation).
• Linux (X11/Xorg or XWayland) for deterministic selectors/listing; ffmpeg required on PATH.
• Linux Wayland-only sessions can use --portal (requires xdg-desktop-portal + backend + PipeWire).
• Screen Recording permission granted on macOS (use screen-record --preflight / --request-permission).

Inputs:

• Natural-language user intent (assistant translates into a command).
• Exactly one mode:
• Discovery: --list-windows, --list-apps, or --list-displays, or
• Permissions: --preflight or --request-permission, or
• Screenshot mode: --screenshot, or
• Recording mode (default when no other mode flag is present).
• Recording selectors (exactly one):
• --portal, or
• --window-id , or
• --active-window, or
• --app (optional --window-name with --app), or
• --display, or
• --display-id .
• Screenshot selectors (exactly one):
• --portal, or
• --window-id , or
• --active-window, or
• --app (optional --window-name with --app).
• Recording args:
• --duration (required for recording)
• --path (required for recording)
• optional: --audio off|system|mic|both, --format mov|mp4
• optional diagnostics: --metadata-out , --diagnostics-out
• Screenshot args:
• optional: --path or --dir , --image-format png|jpg|webp
• optional diff-aware publish: --if-changed, --if-changed-baseline , --if-changed-threshold

Outputs:

• Capture success (recording/screenshot): stdout prints only the resolved output file path (one line).
• List success: stdout prints only UTF-8 TSV rows (no header), one per line.
• Preflight/request success: stdout is empty; any user messaging goes to stderr.
• Errors: stdout is empty; stderr contains user-facing errors (no stack traces).

Exit codes:

• 0: success
• 1: runtime failure
• 2: usage error (invalid flags/ambiguous selection/invalid format)

Failure modes:

• screen-record missing on PATH.
• Linux X11 selectors/list modes used without DISPLAY (Wayland-only session) and without --portal.
• Linux runtime missing required dependencies (for example: ffmpeg, portal backend, or pactl for audio capture).
• Screen Recording permission missing/denied.
• Ambiguous --app / --window-name selection (exit 2 with candidates on stderr).
• Invalid flag combinations (e.g., --window-name without --app, --audio both with .mp4, --format/--image-format conflicts with

--path extension, --portal with non-off audio, display selectors in screenshot mode, or recording-only flags used with --screenshot).

• --metadata-out / --diagnostics-out used outside recording mode.
• --if-changed-baseline path does not exist.

Guidance

Preferences (optional; honor when provided)

• Selector: --active-window for “capture what I’m looking at”; otherwise prefer --window-id for deterministic selection.
• For desktop/non-window capture, prefer --display (or --display-id for deterministic target).
• Output path: prefer a canonical run directory from agent-out project --topic screen-record --mkdir.
• Recording container: default .mov; use .mp4 only when compatible with requested audio.
• Screenshot format: default .png; use .jpg/.webp only when explicitly requested.
• Audio: default off; use system/mic/both only when explicitly requested (recording only).
• Diagnostics files (--metadata-out, --diagnostics-out): only add when user asks for machine-readable artifacts.

Policies (must-follow per request)

1. If underspecified enough to block a valid screen-record command: ask must-have questions first

• Follow the blocking-question format in skills/workflows/conversation/requirements-gap-scan/SKILL.md.
• Ask 1-5 "Need to know" questions with explicit defaults (mode, selector, duration for recording, audio, output path/format, portal

usage on Wayland).

• Do not run commands until the user answers or explicitly approves assumptions.

1. Single entrypoint (do not bypass)

• Only run: screen-record (from PATH; install via brew install nils-cli).
• Do not call other screen recording tools unless debugging screen-record itself.

1. Mode/flag gates (exactly one)

• Exactly one mode: --list-windows / --list-apps / --list-displays / --preflight / --request-permission / --screenshot /

recording.

• Recording requires:
• exactly one selector: --portal / --window-id / --active-window / --app / --display / --display-id
• --duration and --path
• Screenshot requires:
• exactly one selector: --portal / --window-id / --active-window / --app
• display selectors (--display, --display-id) are invalid
• recording-only flags (--duration, --audio, --format, --metadata-out, --diagnostics-out) are invalid
• --metadata-out / --diagnostics-out are valid only in recording mode.
• --if-changed, --if-changed-baseline, --if-changed-threshold are valid only with --screenshot.
• --window-name is only valid with --app.
• --portal is interactive; in recording mode it currently supports --audio off only.
• --audio both requires .mov (or --format mov).

1. Completion response (fixed)

• After a successful run, respond using:
• skills/tools/media/screen-record/references/ASSISTANT_RESPONSE_TEMPLATE.md
• Include clickable output path(s) and a one-sentence “next prompt” that repeats the same capture task with concrete flags/paths.

References

• Full guide: skills/tools/media/screen-record/references/SCREEN_RECORD_GUIDE.md
• Completion template: skills/tools/media/screen-record/references/ASSISTANT_RESPONSE_TEMPLATE.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: graysurf
• Source: graysurf/agent-kit
• License: MIT

Install and usage instructions live in the source repository linked above.