前言¶
Agent 寫前端、改桌面應用時，常會卡在同一類問題上：代碼改完了，但看不到真實界面長什麼樣。瀏覽器裏可以用 Playwright 截頁面，Figma 裏也有專門的設計稿導出能力；可一旦對象變成系統級窗口、多顯示器桌面，或者某個沒有集成截圖接口的原生應用，工具鏈就斷了。
screenshot 就是補這一環的 Agent Skill。它指導 Agent 按操作系統能力做全屏、窗口或像素區域截圖，把結果存成圖片路徑，再交給視覺分析工具逐張查看。本文基於 OpenAI 官方倉庫中的 Skill 原文與安裝說明整理，說明它是什麼、怎麼裝、怎麼用，以及和 Playwright、Figma 如何配合。
這是什麼¶
screenshot 是 OpenAI 在 openai/skills 倉庫 .curated 目錄下維護的一組可複用能力包。目錄裏包含 SKILL.md 指令，以及跨平臺截圖腳本（macOS/Linux 用 Python，Windows 用 PowerShell），外加 macOS 權限預檢與窗口信息輔助腳本。
它的定位很明確：當用戶明確要求桌面/系統截圖，或者工具專用截圖能力拿不到目標畫面時，用操作系統級捕獲補齊視覺輸入。Skill 本身遵循通用的 Agent Skills 格式（SKILL.md + 可選 scripts/），因此在 Codex、Cursor、Claude Code 等支持該標準的 AI 編程工具中都可以按各自目錄放置後使用。
需要注意：倉庫 README 已標註 openai/skills 進入廢棄遷移階段，後續 Codex 技能與插件示例會轉向 openai/plugins。當前若仍從 curated 列表安裝，可繼續用下文的 $skill-installer 方式；長期分發建議關注官方插件文檔。
核心功能與亮點¶
根據官方 SKILL.md，主要能力可以歸納爲下面幾類。
1、保存位置規則清晰
用戶指定路徑就存到該路徑；只說「截一張圖」則存到系統默認截圖目錄；Agent 爲自己做視覺檢查時，存到臨時目錄（--mode temp）。腳本每次輸出一行（或多行）圖片路徑，方便後續用看圖工具按順序打開。
2、工具優先級：先專用、後系統
有 Figma MCP/Skill 就先截設計稿；有 Playwright / agent-browser 就先截瀏覽器或 Electron 頁面。只有用戶明確要求系統截圖、需要整桌面捕獲，或專用工具夠不着時，才啓用本 Skill。對沒有更好集成方案的桌面應用，它才作爲默認截圖手段。
3、多平臺、多粒度捕獲
- 全屏
- 像素區域（x,y,w,h）
- 當前焦點窗口
- macOS 上還可按應用名、窗口標題子串、window id 捕獲，並支持 --list-windows 先列窗口再截
- 多顯示器：macOS 全屏會按顯示器各存一份；Linux/Windows 全屏是虛擬桌面整圖，需要單屏時用 --region 裁切
4、macOS 權限預檢
窗口/應用級截圖前，可先跑 scripts/ensure_macos_permissions.sh，集中檢查並申請 Screen Recording 權限，減少反覆彈窗。官方建議把預檢和截圖寫在同一條命令裏，降低沙箱多次授權。
5、Linux 工具自動選型
Python 助手會按順序嘗試 scrot → gnome-screenshot → ImageMagick import；都沒有就提示用戶安裝。座標區域截圖依賴 scrot 或 import。--app / --window-name / --list-windows 僅 macOS 可用；Linux 側用 --active-window 或在可用時提供 --window-id。
這些能力合在一起，正好支撐「設計稿 vs 實現」「改 UI 前後對比」「桌面應用視覺自檢」這類視覺 QA 鏈路：Figma 出設計、Playwright 出網頁、screenshot 出桌面/原生窗口。
安裝與啓用¶
在 Codex 中安裝（官方 curated 方式）¶
curated 技能可用 Codex 內置的 $skill-installer 按名稱安裝（默認從 skills/.curated 拉取）：
$skill-installer screenshot
也可以直接給出 GitHub 目錄地址：
$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/screenshot
安裝後如未出現在技能列表中，按官方說明重啓 Codex 再試。
在 Cursor / Claude Code 等工具中手動啓用¶
Skill 本質是一個文件夾。把 screenshot 目錄放到對應工具會掃描的 skills 路徑即可，目錄內至少要有 SKILL.md，並保留 scripts/ 等附屬文件。
常見路徑（項目級 / 用戶級）：
| 工具 | 項目級目錄 | 用戶級目錄 |
|---|---|---|
| Cursor | .cursor/skills/screenshot/ 或 .agents/skills/screenshot/ |
~/.cursor/skills/screenshot/ 或 ~/.agents/skills/screenshot/ |
| Codex | .agents/skills/screenshot/ |
~/.agents/skills/（installer 默認也會裝到 $CODEX_HOME/skills/，常見爲 ~/.codex/skills/） |
| Claude Code | .claude/skills/screenshot/ |
~/.claude/skills/screenshot/ |
手動示例（以 Cursor 項目級爲例）：
mkdir -p .cursor/skills
# 克隆倉庫後拷貝 curated 目錄，或 sparse checkout 該子目錄
cp -R /path/to/openai/skills/skills/.curated/screenshot .cursor/skills/screenshot
Cursor 啓動後會自動發現 skills；也可在 Agent 對話裏用 / 搜索 screenshot 手動調用。只要 scripts/ 還在，Agent 才能按 SKILL.md 裏的路徑執行真實截圖命令。
典型用法示例¶
以下命令均來自官方 SKILL.md，把 <path-to-skill> 換成本機 Skill 根目錄。
macOS / Linux：Python 助手¶
默認截一張圖（存系統默認位置）：
python3 <path-to-skill>/scripts/take_screenshot.py
Agent 自檢用臨時目錄：
python3 <path-to-skill>/scripts/take_screenshot.py --mode temp
指定輸出路徑：
python3 <path-to-skill>/scripts/take_screenshot.py --path output/screen.png
按應用名截窗口（僅 macOS，支持子串匹配，匹配到多個窗口會各出一張）：
python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex"
應用內再按窗口標題過濾，或先列出 window id：
python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex" --window-name "Settings"
python3 <path-to-skill>/scripts/take_screenshot.py --list-windows --app "Codex"
像素區域與當前焦點窗口：
python3 <path-to-skill>/scripts/take_screenshot.py --mode temp --region 100,200,800,600
python3 <path-to-skill>/scripts/take_screenshot.py --mode temp --active-window
macOS 推薦「權限預檢 + 截圖」一次跑完：
bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex" --mode temp
官方工作流例子：用戶說「幫我看看界面上有什麼」→ 截到 temp → 按打印出的路徑依次打開看圖；用戶說「Figma 設計和實現不一致」→ 先用 Figma 相關能力截設計稿，再用本 Skill 截運行中的應用，對比原始截圖，不要先做不必要的圖像加工。
Windows：PowerShell 助手¶
powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1
powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp
powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Path "C:\Temp\screen.png"
powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp -Region 100,200,800,600
powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp -ActiveWindow
使用 -ActiveWindow 前，需要用戶先把目標窗口置於前臺。
助手不可用時的系統命令回退¶
官方還給出了直接調用系統命令的回退寫法，例如 macOS 的 screencapture、Linux 的 scrot / gnome-screenshot / import。能跑捆綁腳本時優先用腳本，避免自己拼平臺差異。
適用場景與注意事項¶
適合的場景
- 桌面/原生應用的視覺檢查與調試
- UI 改動前後的界面留證、簡單視覺迴歸對比
- 多顯示器環境下定位某一塊屏幕區域
- 配合 Figma（設計）與 Playwright（瀏覽器/Electron）做「設計 → 實現 → 運行態」對照
使用時注意
- macOS 必須解決 Screen Recording 權限；沙箱裏若出現截屏被攔截、無法從顯示器創建圖像、Swift ModuleCache 權限報錯，需要提升權限後重跑。
- 應用/窗口截不到時，先
--list-windows --app "AppName"，確認應用在屏幕上可見，再改用--window-id。 - Linux 區域/窗口失敗時，先
command -v scrot、gnome-screenshot、import檢查依賴。 - 存到系統默認截圖目錄若因沙箱權限失敗，同樣需要提權重試。
- 始終在回覆裏報告保存路徑；多窗口或多顯示器匹配時會輸出多行路徑，並帶
-w/-d一類後綴，需要逐張查看。 - 不要把本 Skill 當成瀏覽器截圖的第一選擇：網頁場景優先 Playwright 等專用工具。
小結¶
screenshot 把「操作系統級截圖」打包成 Agent 可發現、可執行的 Skill：統一保存策略、跨平臺助手腳本、清晰的工具優先級，以及和 Figma、Playwright 銜接的視覺 QA 工作流。裝好之後，Agent 不再只能「猜界面」，而是能真正拍下桌面畫面再分析。
官方地址：https://github.com/openai/skills/tree/main/skills/.curated/screenshot
Skill 原文（SKILL.md）：https://raw.githubusercontent.com/openai/skills/main/skills/.curated/screenshot/SKILL.md
Codex Skills 說明：https://developers.openai.com/codex/skills
Cursor Skills 說明：https://cursor.com/docs/skills
Agent Skills 開放標準：https://agentskills.io
