Screenshot

Screenshot

Capture screenshots through screen-record (macOS/Linux) and optional desktop capture via screencapture on macOS.

Contract

Prereqs:

• screen-record available on PATH (install via brew install nils-cli).
• agent-out available on PATH for canonical default artifact directories (also from nils-cli).
• macOS: Screen Recording permission granted (use screen-record --preflight / --request-permission).
• Linux: follow screen-record runtime prerequisites (X11 selectors or Wayland --portal, plus required dependencies).
• screencapture (built-in on macOS) only when using --desktop.
• bash for scripts/screenshot.sh (wrapper).

Inputs:

• scripts/screenshot.sh is a wrapper around screen-record; --desktop uses screencapture.
• Mode selection:
• Default: screenshot mode (wrapper adds --screenshot unless a pass-through mode is present).
• Desktop helper: --desktop captures the main display via screencapture (macOS only).
• Discovery: --list-windows / --list-apps / --list-displays.
• Permissions: --preflight / --request-permission.
• Version: --version / -V pass through to screen-record.
• Screenshot selectors (choose one):
• --portal, or
• --window-id , or
• --active-window, or
• --app (optional --window-name with --app).
• Screenshot output args:
• --path (recommended), or
• --dir (used when --path is omitted), plus optional --image-format png|jpg|webp.

Outputs:

• Screenshot success: stdout prints only the resolved output image 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 or missing dependency
• 2: usage error (invalid flags/ambiguous selection/unsupported platform)

Failure modes:

• screen-record missing on PATH.
• Screen Recording permission missing/denied (macOS).
• Linux X11 selectors/list modes used without DISPLAY (use --portal on Wayland-only sessions).
• screen-record runtime dependencies missing (for example: portal backend on Wayland-only sessions).
• Ambiguous --app / --window-name selection (no single match).
• Invalid flag combinations.
• --desktop used on non-macOS.
• --desktop only supports --image-format png|jpg.

Scripts (only entrypoints)

• $AGENT_HOME/skills/tools/media/screenshot/scripts/screenshot.sh

Usage

• Resolve a canonical project artifact directory:

artifact_dir="$(agent-out project --topic screenshot --mkdir)"

• Screenshot active window:

$AGENT_HOME/skills/tools/media/screenshot/scripts/screenshot.sh --active-window --path "$artifact_dir/active-window.png"

• Screenshot via portal picker (Linux Wayland):

$AGENT_HOME/skills/tools/media/screenshot/scripts/screenshot.sh --portal --path "$artifact_dir/portal.png"

• Screenshot the desktop (main display helper, macOS only):

$AGENT_HOME/skills/tools/media/screenshot/scripts/screenshot.sh --desktop --path "$artifact_dir/desktop.png"

• List windows to find a --window-id:

$AGENT_HOME/skills/tools/media/screenshot/scripts/screenshot.sh --list-windows

• List displays (pass-through to screen-record):

$AGENT_HOME/skills/tools/media/screenshot/scripts/screenshot.sh --list-displays

• Screenshot by app/window title:

$AGENT_HOME/skills/tools/media/screenshot/scripts/screenshot.sh --app "Terminal" --window-name "Docs" --path "$artifact_dir/terminal-docs.png"

• Permission preflight / request (if blocked):

screen-record --preflight
screen-record --request-permission

Notes

• Prefer agent-out project --topic screenshot --mkdir for ad hoc screenshot paths so outputs are grouped by project/run.
• For non-window video capture, use screen-record --display / --display-id (recording mode).

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.