mac screenshot

Capture macOS screenshots for the whole screen, a specific app window, or a precisely targeted desktop window using built-in system tools. Use when the user...

Security Scan

The skill's requirements, instructions, and included script are coherent with its stated purpose (macOS screenshot capture) and do not request unrelated credentials or perform hidden network activity.

Purpose & Capability

Name/description match the actual behavior: it enumerates macOS windows via inline Swift/CoreGraphics and uses screencapture to take window or full-screen screenshots. Required binaries (swift, screencapture, python3) are appropriate for that workflow.

Instruction Scope

SKILL.md and the bundled script only enumerate on-screen windows, filter by keyword, and invoke screencapture. Instructions explicitly treat screenshots as sensitive and require user consent before sending into chat. No instructions to read unrelated files, network endpoints, or other credentials are present.

Install Mechanism

This is an instruction-only skill with a small included shell script and inline Swift; there is no download/install step or external artifact retrieval. Nothing is written to system locations beyond creating a local 'screenshots' folder when saving captures.

Credentials

The skill requests no environment variables or credentials. The use of swift and python3 is proportional to the implementation approach. No unrelated secrets or config paths are required.

Persistence & Privilege

The skill is not marked always:true and does not modify other skills or system configuration. It may require granting macOS Screen Recording or Accessibility permissions to the host process, which is expected for screenshot functionality but should be granted deliberately by the user.

Assessment

This skill appears consistent with its description, but remember: screenshots can contain sensitive data. Before installing or using it, (1) inspect the included script to confirm you are comfortable with its behavior (it only enumerates windows and runs screencapture), (2) be prepared to grant macOS Screen Recording (and possibly Accessibility) to the host process that runs the commands—only grant those permissions to a trusted process, (3) the skill saves files locally (e.g., screenshots/); review where artifacts are stored and who can access them, and (4) the skill does not contact external servers or request credentials, so network exfiltration is not evident from the code. If you want extra assurance, run the script manually in a controlled environment before granting persistent permission to an agent.

Capture screenshots on macOS with built-in tools only.

Default workflow

1. For a full-screen capture, use screencapture -x <output>.
2. For a specific app window, first try to enumerate windows with inline Swift + CoreGraphics.
3. Filter returned windows by owner and name, matching keywords like weixin, wechat, or the app name the user gave.
4. Prefer a window whose sharing is 1.
5. Capture the exact window with screencapture -x -l <windowId> <output>.
6. Save under the workspace.
7. Return the local path by default.
8. Only send or attach the screenshot into the current chat if the user explicitly asks for it.
9. Treat screenshots as potentially sensitive because they may contain confidential on-screen information.

Scripted path

Prefer the bundled script when available:

scripts/capture-window-by-keyword.sh <keyword> [output_path]
scripts/capture-window-by-keyword.sh --list <keyword>
scripts/capture-window-by-keyword.sh --index <n> <keyword> [output_path]

Examples:

scripts/capture-window-by-keyword.sh wechat
scripts/capture-window-by-keyword.sh --list wechat
scripts/capture-window-by-keyword.sh --index 2 wechat

The script:

• enumerates on-screen windows with inline Swift + CoreGraphics
• filters by keyword against owner and name
• supports alias matching, for example weixin -> wechat, wx
• can list multiple matches without capturing
• can capture a specific match by 1-based index
• otherwise prefers a window with sharing = 1
• captures the exact window with screencapture -x -l <windowId>
• prints the output PNG path
• returns a local artifact by default
• only attach or send the PNG if the user explicitly asks for delivery into chat

Proven method for targeting a window by keyword

Use this exact pattern to locate candidate windows:

swift - <<'SWIFT'
import CoreGraphics
import Foundation

let options = CGWindowListOption(arrayLiteral: .optionOnScreenOnly, .excludeDesktopElements)
let windows = (CGWindowListCopyWindowInfo(options, kCGNullWindowID) as? [[String: Any]]) ?? []

let matches = windows.compactMap { w -> [String: Any]? in
    let owner = (w[kCGWindowOwnerName as String] as? String) ?? ""
    let name = (w[kCGWindowName as String] as? String) ?? ""
    let low = (owner + " " + name).lowercased()
    guard low.contains("weixin") || low.contains("wechat") else { return nil }

    return [
        "id": w[kCGWindowNumber as String] ?? "",
        "owner": owner,
        "name": name,
        "sharing": w[kCGWindowSharingState as String] ?? "",
        "bounds": w[kCGWindowBounds as String] ?? ""
    ]
}

let data = try! JSONSerialization.data(withJSONObject: matches, options: [.prettyPrinted])
print(String(data: data, encoding: .utf8)!)
SWIFT

Typical success indicators:

• owner or name matches the requested app/window
• id is present
• sharing = 1

Then capture the window:

screencapture -x -l <windowId> <output.png>

Lessons learned / success criteria

• Do not depend on Python Quartz; it may not be installed.
• Do not depend on System Events window attributes for window IDs; some apps do not expose AXWindowNumber reliably.
• Inline Swift calling CGWindowListCopyWindowInfo is the most reliable built-in approach on macOS.
• screencapture -l <windowId> is a true system window capture, not a cropped full-screen image.
• If enumeration succeeds but capture fails, inspect whether the target window is shareable and on screen.

Troubleshooting

If screencapture works for full screen but not for a window

Check whether the enumerated target has sharing = 1. If not, tell the user the app/window is not currently shareable for window capture and ask them to bring it to the front and try again.

If System Events says assistive access is not allowed

Do not rely on that path. Prefer the Swift + CoreGraphics method. If the user still wants UI-structure inspection, tell them to enable:

• System Settings → Privacy & Security → Accessibility
• Turn on access for the actual host process running the agent, often openclaw-gateway, Terminal, or the active terminal host

If screen capture is blocked

Tell the user to enable:

• System Settings → Privacy & Security → Screen & System Audio Recording (or Screen Recording on older macOS)
• Grant permission to the actual host process running the command

If swift is not found

Tell the user to install Xcode Command Line Tools manually:

xcode-select --install

If that fails or they want the GUI path, tell them to install Xcode from the App Store or re-run the command after opening Software Update.

Output location

Prefer saving screenshots into a workspace subdirectory like:

• screenshots/
• captures/

Use descriptive filenames with timestamps when the user may request multiple captures.

Privacy and chat delivery rule

Treat screenshots as potentially sensitive local artifacts.

When a screenshot request comes from a chat surface:

• capture the screenshot first
• save it locally by default
• only send the PNG into the current chat if the user explicitly asks for delivery or attachment
• if explicit delivery is requested and an explicit messaging tool is available, prefer using it to send the file into the current conversation