Skill: mallocfeng/macscreenshot (version 1.0.1)

--- name: macscreenshot description: 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 asks to screenshot the desktop, a frontmost app, a WeChat/Weixin window, a Chrome window, or to locate a macOS window by keyword and capture it. Prefer the built-in screencapture command and CoreGraphics window enumeration via inline Swift. If required capabilities are missing, tell the user exactly which macOS permissions to enable; if Swift tooling is unavailable, tell the user how to install Xcode Command Line Tools manually. metadata: {"clawdbot":{"emoji":"📸","os":["darwin"],"requires":{"bins":["swift","screencapture","python3"]},"install":[{"id":"xcode-clt","kind":"shell","command":"xcode-select --install","bins":["swift"],"label":"Install Xcode Command Line Tools"}]}} --- # macscreenshot 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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

path: references/success-notes.md
content: # screenshot skill - success notes

## Confirmed successful path

Environment:
- macOS built-in tools only
- No extra screenshot software required
- No Python Quartz dependency required

Working sequence:
1. Use inline Swift to call `CGWindowListCopyWindowInfo`
2. Filter windows by `owner` and `name`
3. Read `kCGWindowNumber` as the window ID
4. Confirm `kCGWindowSharingState == 1` when possible
5. Run `screencapture -x -l <windowId> <output>`

## Real-world notes from WeChat capture

- App matched: `WeChat`
- A successful capture used a window entry like:
  - `id = 207`
  - `owner = WeChat`
  - `name = WeChat`
  - `sharing = 1`
- This was sufficient for `screencapture -l 207` to produce a PNG.

## Failure modes observed

### Python route failed

`ModuleNotFoundError: No module named 'Quartz'`

Interpretation:
- pyobjc / Quartz bindings are not guaranteed to exist
- Do not assume Python can enumerate macOS windows

### AppleScript AX window route failed

`Can't get attribute "AXWindowNumber"`

Interpretation:
- Some apps do not expose a usable `AXWindowNumber`
- Accessibility inspection is not a reliable way to obtain the screenshot window ID

### Accessibility denied

`osascript is not allowed assistive access`

Interpretation:
- Only relevant if using `System Events`
- Avoid this dependency when possible

## Recommendation

Prefer Swift + CoreGraphics first. Only mention Accessibility permissions when a task explicitly requires `System Events` or other UI scripting.


path: scripts/capture-window-by-keyword.sh
content: #!/usr/bin/env bash
set -euo pipefail

usage() {
  cat >&2 <<'EOF'
Usage:
  capture-window-by-keyword.sh <keyword> [output_path]
  capture-window-by-keyword.sh --list <keyword>
  capture-window-by-keyword.sh --index <n> <keyword> [output_path]

Options:
  --list       List matched windows only, do not capture
  --index <n>  Choose the nth matched window (1-based)

Notes:
  - Supports keyword aliases, e.g. weixin -> wechat, wx
  - Without --index, prefers the first shareable window (sharing = 1)
EOF
}

if [[ $# -lt 1 ]]; then
  usage
  exit 1
fi

LIST_ONLY=0
INDEX=""
POSITIONAL=()
while [[ $# -gt 0 ]]; do
  case "$1" in
    --list)
      LIST_ONLY=1
      shift
      ;;
    --index)
      [[ $# -ge 2 ]] || { usage; exit 1; }
      INDEX="$2"
      shift 2
      ;;
    -h|--help)
      usage
      exit 0
      ;;
    *)
      POSITIONAL+=("$1")
      shift
      ;;
  esac
done

[[ ${#POSITIONAL[@]} -ge 1 ]] || { usage; exit 1; }
KEYWORD="${POSITIONAL[0]}"
OUTPUT_PATH="${POSITIONAL[1]:-}"
TIMESTAMP="$(date +%Y%m%d-%H%M%S)"

if [[ -z "$OUTPUT_PATH" && "$LIST_ONLY" -eq 0 ]]; then
  OUTPUT_DIR="$(pwd)/screenshots"
  mkdir -p "$OUTPUT_DIR"
  SAFE_KEYWORD="$(printf '%s' "$KEYWORD" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-')"
  OUTPUT_PATH="$OUTPUT_DIR/${SAFE_KEYWORD:-window}-${TIMESTAMP}.png"
elif [[ -n "$OUTPUT_PATH" ]]; then
  mkdir -p "$(dirname "$OUTPUT_PATH")"
fi

if ! command -v swift >/dev/null 2>&1; then
  echo "Error: swift not found." >&2
  echo "Install Xcode Command Line Tools manually:" >&2
  echo "  xcode-select --install" >&2
  exit 2
fi

MATCH_JSON="$(swift - "$KEYWORD" <<'SWIFT'
import CoreGraphics
import Foundation

let rawKeyword = (CommandLine.arguments.dropFirst().first ?? "").lowercased()
var terms: [String] = [rawKeyword]
let aliasMap: [String: [String]] = [
    "weixin": ["wechat", "wx"],
    "wechat": ["weixin", "wx"],
    "telegram": ["tg"],
    "chrome": ["google chrome"],
    "qq": ["tencent qq"]
]
if let aliases = aliasMap[rawKeyword] {
    terms.append(contentsOf: aliases)
}
terms = Array(Set(terms.filter { !$0.isEmpty }))

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 terms.contains(where: { low.contains($0) }) 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: [])
print(String(data: data, encoding: .utf8)!)
SWIFT
)"

if [[ -z "$MATCH_JSON" || "$MATCH_JSON" == "[]" ]]; then
  echo "Error: no on-screen window matched keyword '$KEYWORD'." >&2
  exit 3
fi

MATCH_JSON="$MATCH_JSON" python3 - <<'PY'
import os, json
arr = json.loads(os.environ['MATCH_JSON'])
for i, item in enumerate(arr, 1):
    print(f"[{i}] id={item.get('id')} sharing={item.get('sharing')} owner={item.get('owner')} name={item.get('name')} bounds={item.get('bounds')}")
PY

if [[ "$LIST_ONLY" -eq 1 ]]; then
  exit 0
fi

WINDOW_ID="$(MATCH_JSON="$MATCH_JSON" INDEX="$INDEX" python3 - <<'PY'
import os, json, sys
arr = json.loads(os.environ['MATCH_JSON'])
idx = os.environ.get('INDEX', '').strip()
if not arr:
    raise SystemExit(1)
if idx:
    n = int(idx)
    if n < 1 or n > len(arr):
        print(f'Error: index {n} out of range (1-{len(arr)}).', file=sys.stderr)
        raise SystemExit(2)
    print(arr[n-1]['id'])
else:
    arr.sort(key=lambda x: 0 if str(x.get('sharing')) == '1' else 1)
    print(arr[0]['id'])
PY
)"

if ! screencapture -x -l "$WINDOW_ID" "$OUTPUT_PATH"; then
  echo "Error: screencapture failed for window id $WINDOW_ID." >&2
  echo "Check Screen Recording permission for the host process in macOS Settings." >&2
  exit 4
fi

if [[ ! -f "$OUTPUT_PATH" ]]; then
  echo "Error: screenshot file was not created." >&2
  exit 5
fi

echo "$OUTPUT_PATH"


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)