# Screen Record > Capture recordings or screenshots for a window/display via the screen-record CLI (macOS 12+ and Linux). - **Type:** Skill - **Install:** `agentstack add skill-graysurf-agent-kit-screen-record` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [graysurf](https://agentstack.voostack.com/s/graysurf) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [graysurf](https://github.com/graysurf) - **Source:** https://github.com/graysurf/agent-kit/tree/main/skills/tools/media/screen-record ## Install ```sh agentstack add skill-graysurf-agent-kit-screen-record ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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. 2. 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. 3. 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`). 4. 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](https://github.com/graysurf) - **Source:** [graysurf/agent-kit](https://github.com/graysurf/agent-kit) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-graysurf-agent-kit-screen-record - Seller: https://agentstack.voostack.com/s/graysurf - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.