Home / All Skills / Docs & Knowledge / capture-screen
English (EN)简体中文 (ZH)日本語 (JA)
Docs & Knowledge · daymade/claude-code-skills

capture-screen

Programmatic screenshot capture on macOS. Find window IDs with Swift CGWindowListCopyWindowInfo, control application windows via AppleScript (zoom, scroll, select), and capture with screencapture. Use when automating screenshots, capturing application windows for documentation, or building multi-shot visual workflows.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit
Author daymadeGitHub daymade/claude-code-skills ↗Stars 1385License MIT（仓库根 LICENSE，Copyright (c) 2025 daymade；GitHub API spdx MIT）Commit d5c4678cb5
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

A three-step workflow built entirely on native macOS tools: Swift + CoreGraphics enumerates windows to get the WID → AppleScript/osascript controls the view → screencapture -l <WID> performs precise screen capture.

daymade-macos/capture-screen/SKILL.md
1. Find Window → Swift CGWindowListCopyWindowInfo → get numeric Window ID 2. Control View → AppleScript (osascript) → zoom, scroll, select 3. Capture → screencapture -l <WID> → PNG/JPEG output
No proprietary screenshot engine; it leverages native macOS capabilities throughout the entire chain: screencapture is the built-in screenshot CLI, osascript is the system AppleScript interpreter, and the Swift script handles window enumeration exclusively.

Window discovery uses the Swift script get_window_id.swift invoking CoreGraphics CGWindowListCopyWindowInfo(.optionOnScreenOnly), filtering by app name/title keyword to output WID=… | App=… | Title=….

daymade-macos/capture-screen/scripts/get_window_id.swift
CGWindowListCopyWindowInfo( .optionOnScreenOnly, kCGNullWindowID ) as? [[String: Any]] else {
SKILL.md states this is the only reliable method on macOS (System Events' `id of window` is not the CGWindowID required by screencapture; PyObjC Quartz often fails due to missing installations—see the 'Failed Approaches (DO NOT USE)' table).

View control layer: Excel has full AppleScript dictionary support (activate, zoom, scroll row/column, select range, switch sheets, open files); arbitrary apps rely on basic activate / System Events AXRaise; restricted apps fall back to keyboard simulation.

daymade-macos/capture-screen/SKILL.md
osascript -e 'tell application "Microsoft Excel" set scroll row of active window to 45 end tell'
Documentation differentiates control depth via the 'Supported Applications' table: Excel is the most comprehensive, Chrome provides basics, and generic activate + screencapture is guaranteed to work for the rest; AppleScript may hang → always recommended to wrap in a timeout.

Capture layer: screencapture -l <WID> precisely captures the specified window (-x for mute, -t jpg, -T delay, -R region), and Retina 2x outputs are scaled back to 1x using sips.

daymade-macos/capture-screen/SKILL.md
# Silent capture (no camera shutter sound) screencapture -x -l <WID> output.png
Physical workflow example: multi-segment scrolling to capture long tables (sleep 1 after each scroll before capturing; WID must be re-acquired after app restarts or window reopens, as CGWindowID becomes invalid).

Triple-check permission troubleshooting template: Screen Recording permission is mandatory; helper binaries (swift/python/terminal) and packaged .app bundles have different TCC authorization identities; the script provides --permission-hint screen/microphone to print troubleshooting guidance.

daymade-macos/capture-screen/SKILL.md
`swift scripts/get_window_id.swift` reads on-screen windows via CoreGraphics, so it needs Screen Recording permission on macOS.
`printPermissionContextHint()` within get_window_id.swift enumerates invoker/runtime/script candidate identities and notes that 'In most cases the entry shown in TCC is the helper process'; this turns real-world permission triage experience into a reusable template.

Documented failed paths (DO NOT USE): System Events `id of window` (-1728), Python PyObjC Quartz (ModuleNotFoundError), and osascript `window id` (incorrect format)—preventing execution models from repeating mistakes.

daymade-macos/capture-screen/SKILL.md
| `System Events` → `id of window` | Error -1728 | System Events cannot access window IDs in the format screencapture needs |
This 'proven unworkable' checklist is a signature feature of this skill: it eliminates trial-and-error costs up front, guiding the model directly onto working paths.

2Core Capabilities

01Enumerate all on-screen windows or filter by keyword, outputting CGWindowID (WID=12345 | App=… | Title=…)
02Precisely control Excel views via AppleScript: zoom / scroll row/column / select range / switch sheets / open files
03Activate arbitrary apps / bring to front by index via AXRaise (System Events)
04Capture window screenshots by WID (PNG/JPEG, silent mode, delay, region capture)
05Retina 2x→1x downscaling (sips) and screenshot pixel verification (ls/file)
06Multi-segment capture workflow: scroll-and-page long tables/multiple sheets (sleep synchronization + WID re-fetching discipline)
07Permission triage: --permission-hint screen|microphone prints Settings paths and identity troubleshooting checklists

3External Dependencies

KindDependency / Endpoint
cliswift（运行 get_window_id.swift 或 -e 内联执行 CoreGraphics 枚举）
cliscreencapture（macOS 系统自带，窗口/区域截图）
cliosascript / System Events（AppleScript 控制 app 窗口）
clisips / ls / file / timeout（可选缩放与校验、超时保护）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
  • scripts/: Execute local scripts or commands: swift scripts/get_window_id.swift (or inline window enumeration with swift -e)
  • 本地工作目录: File read/write and artifact output: screenshot output files (output.png/output.jpg, etc., with paths specified by caller)
Audit Notes: Purely local macOS toolchain: executes native swift/screencapture/osascript/sips with no outbound network traffic, no credential access, and no third-party dependencies; writes local image files. Note: Requires Screen Recording privacy authorization. Screenshot contents and window titles constitute sensitive local data (no outbound exposure surface), and System Events keyboard simulation can interact with arbitrary apps—all strictly within host local permission boundaries.

5Second-Pass Verification

  • [ok] Swift 脚本只做窗口枚举（无隐藏行为） — get_window_id.swift 逻辑 = 参数解析 + CGWindowListCopyWindowInfo(.optionOnScreenOnly) + 过滤打印 + 权限提示文本；无文件写/网络/进程执行调用。
  • [ok] 三步工作流与 description 声明一致 — Find Window/Control View/Capture 三步概览代码块、Step1-3 正文、Quick Start 命令逐字对应；Excel 控制命令含 zoom/scroll/select/sheet。
  • [ok] screencapture -l 兼容 CGWindowID 的说法有失败表佐证 — Failed Approaches 表记录 System Events id of window 报 -1728 等三个失败路径，反向支持『Swift 枚举 + screencapture -l』为主路径。
  • [ok] 无网络/无凭证（安全结论基础） — 全目录 token 扫描零网络/凭证命中；依赖全部是 macOS 系统自带 CLI。
  • [ok] TCC/Screen Recording 依赖表述准确 — SKILL.md Permission Troubleshooting 与脚本 --permission-hint 均明示 Screen Recording 为前置条件，并处理 helper binary 身份问题。
  • [ok] 元数据（commit/license/stars） — 本地 HEAD == pin d5c4678cb5d4fd6acc9c922690df035dbd33d247；GitHub API：MIT、stars 1385（2026-09-09 实采）、pushed_at 2026-09-09T12:33:29Z。

6Verdict & Scenarios

  • Ready to use with zero dependencies: relies entirely on macOS system tools, requiring no pip/npm/build steps; simply copy and run commands.
  • Documented pitfalls: the Failed Approaches table and permission triage template prevent execution models from taking detours.
  • Deeply polished for Excel scenarios: complete multi-segment capture examples covering zoom/scroll/select/sheet switching can be directly used for reporting/model documentation automation.
  • Systematic solution for permission issues: identifies and templates TCC identity differences between helper binaries and .app bundles.
    • Best for: Suitable for scenarios on macOS requiring programmatic screenshots: segmenting and capturing Excel financial models/reports for documentation, capturing windows of apps like Chrome, building multi-shot visual workflows, and automation requiring precise window-level (rather than full-screen) capture. Most useful for developers and analysts producing product documentation, archiving financial models, or performing UI verification.
    Not for: Not suitable for non-macOS platforms; not suitable for users who do not need window control and only want quick full-screen/regional screenshots (screencapture alone is sufficient without this skill); not suitable for cross-platform screenshot needs or in-app pixel-level content obscured by design (such as password manager masked content); not suitable for restricted environments where Screen Recording permission cannot be granted.
    Install Agent-Ready
    ① Verified Mirror 2026-09-09
    Option A · Direct DownloadDownload capture-screen.tar.gz
    sha256: fb587255b81bdc81…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit d5c4678cb5.