From c0c0b7e8f081a48242253f0ac9e9bd64ae8f9d12 Mon Sep 17 00:00:00 2001 From: TZGyn Date: Tue, 27 Oct 2026 23:40:04 +0800 Subject: [PATCH] Document the Kapture screenshot CLI for agents --- SKILL.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/SKILL.md b/SKILL.md index 986ca3b..92e744a 100644 --- a/SKILL.md +++ b/SKILL.md @@ -683,3 +683,38 @@ it). The UI and API are the same deployment. update; recreate the app to change keys. - For a Coolify deployment failure caused by a stale SHA, see the `uploadpack.allowReachableSHA1InWant` note in section 8. + +## 10. Screenshots for agents (Kapture CLI) + +Kapture ships a `kapture` CLI (installed by the cask) so agents and scripts can +capture app windows or the main display without opening the UI. It is a thin +client: requests go to the running menu-bar app, which holds the Screen +Recording permission — the terminal and the agent need no grant. The app is +launched automatically if it is not running (the first capture after launch is +slower by a second or two). + +```bash +kapture list # id, app, title, size +kapture list --json # machine-readable +kapture capture --app Xcode --out /tmp/xcode.png +kapture capture --app Safari --json # {"ok","path","width","height"} +kapture capture --window-id 1234 --out /tmp/w.png +kapture capture --screen --out /tmp/screen.png +``` + +- **Input:** `--app` takes a localized app name or bundle id (case-insensitive + substring) and captures that app's frontmost window; omit it to capture the + frontmost app's window. `--window-id` takes an id from `kapture list`. + `--screen` captures the main display instead of a window. +- **Output:** `--out ` writes the PNG there (`~` expands; relative paths + resolve against the cwd). Without `--out` the file goes to `$TMPDIR` and the + absolute path is printed on stdout. `--json` prints + `{"ok","path","width","height"}`; errors go to stderr. +- **Exit codes:** 0 ok, 1 capture failed or no matching window, 2 usage error, + 3 the Kapture app did not respond. +- **For agents:** save screenshots outside the repo (`$TMPDIR` or + `/tmp/kapture/`), never commit them, and read the path from stdout instead of + guessing. To screenshot the app you are building, launch it first + (`open .app`), wait for its window to appear, then + `kapture capture --app `; window captures include the chrome and + rounded corners and work even when the window is partly occluded.