前言¶
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
