# Screenshot

> Capture screenshots via screen-record on macOS and Linux, with optional macOS desktop capture via screencapture.

- **Type:** Skill
- **Install:** `agentstack add skill-graysurf-agent-kit-screenshot`
- **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/screenshot

## Install

```sh
agentstack add skill-graysurf-agent-kit-screenshot
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

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

- Screenshot active window:

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

- Screenshot via portal picker (Linux Wayland):

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

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

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

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

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

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

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

- Screenshot by app/window title:

```bash
$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):

```bash
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](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-screenshot
- 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%.