| name | browser-use |
| description | 统一处理浏览器使用任务，支持 CDP 直连/无头模式 使用用户本机 Chromium 系浏览器。Use when the user asks to browse websites, interact with pages, fill forms, capture screenshots, reuse an existing Chrome/Chromium/Edge login session, access internal/login-only pages, handle access-restricted content, when websearch/webfetch are unavailable, or automate browser actions. |
Browser Use
适用范围
当任务需要真实浏览器环境时使用本 skill，包括：
- 打开网页、浏览页面、点击按钮、填写表单
- 截图、抓取页面内容、提取链接或媒体资源
- 访问登录后页面、内部系统、动态渲染页面
- 复用用户当前浏览器的登录态
浏览器使用模式说明
| 模式 | 说明 | 何时使用 |
|---|
agent-browser | 独立浏览器自动化模式 | 用户明确说用 agent-browser |
cdp-direct | 复用本机 Chromium 系浏览器的 CDP 直连模式 | 用户明确说用 CDP 模式 |
cdp-headless | 通过 BU_CDP_WS / BU_CDP_URL 连接独立 headless Chromium 实例 | 只有用户明确要求 headless，或任务本身是后台任务/定时任务，或系统不支持可视化 |
- 用户明确指出模式后，直接阅读执行规则部分
- 当用户没有明确指出使用模式时，进入下一步自动判定
- 不要默认切到
cdp-headless；能用用户正常浏览器完成的任务，优先保持可见浏览器流程
自动判定模式
当用户没有明确指出使用模式时，按下面两步自动判定：
-
先判断本次 cdp-direct 是否需要 headless 浏览器实例
满足以下任一条件时，判定为“使用 headless 浏览器实例的 cdp-direct 流程”：
- 任务天然是后台执行
- 任务属于定时任务、
CI / cron
- 用户明确要求本次使用 headless 浏览器
- 系统不支持可视化，如服务器
-
如果判定需要 headless，则按以下顺序执行
- 先读取
references/cdp-headless.md
- 优先使用显式提供的
BU_CDP_WS / BU_CDP_URL
- 不要引导用户去操作日常浏览器 profile 的 inspect 授权页
- 如果没有显式 CDP endpoint，再按
references/cdp-headless.md 中当前平台对应的后台启动方式启动专用 Chromium 实例；必须让浏览器进程脱离当前 shell 独立存活，并为它分配未被占用的专用 remote debugging 端口，优先复用安装脚本设置的 AGENT_BROWSER_EXECUTABLE_PATH
- 连通后读取
references/cdp-direct.md，后续页面操作统一按 cdp-direct 工作流执行
第一步：跑 CDP 可用性检测
先执行：
flocks browser --doctor
该命令会检查 flocks browser 的 daemon 是否可用、Chrome/Chromium/Edge 是否运行，以及当前是否有可用的浏览器连接。
第二步：根据检测结果决定模式
结果 A：doctor 通过
这时立即确定使用 CDP 直连，然后马上阅读：
之后只按 CDP 流程执行，不再切到 agent-browser。
结果 B：浏览器已运行，但 daemon 或 active browser connection 不可用
必须直接提示用户：
browser: not connected — 请确保 Chrome / Chromium / Edge 已打开，然后访问对应浏览器的 inspect 页面（例如 chrome://inspect/#remote-debugging 或 edge://inspect/#remote-debugging）并勾选 Allow remote debugging
然后等待用户进一步指示，不要直接操作。
当用户确认已开启remote-debugging后:
- 执行
flocks browser --setup 触发交互式 attach，不要用短超时包装该命令
- 再运行
flocks browser --doctor 做只读确认。
- 如果还失败，先执行
flocks browser --reload 清理旧 daemon，再重新执行 flocks browser --setup，避免因为残留 daemon 造成干扰。
如果用户在 Windows PowerShell 中执行 flocks browser -c，优先使用单行代码并用分号分隔；多行单引号字符串容易因为换行/转义处理差异而触发假失败。
- 如果
--setup 成功，随后 --doctor 通过：立即使用 CDP 直连，并立刻阅读 references/cdp-direct.md
结果 C：flocks browser --doctor 失败，或当前机器没有可用 Chrome/Chromium/Edge
说明当前环境不适合 CDP 直连。此时要：
- 明确告诉用户是哪一项不满足，提示需要做什么操作才能达到要求
执行规则
- 模式一旦确定，立即读取对应的 reference。
cdp-headless 是唯一例外：先读取 references/cdp-headless.md 完成浏览器启动与连接，再读取 references/cdp-direct.md 执行通用页面操作。- 在
cdp-headless 中，如果当前任务自己启动了专用浏览器实例，必须记录 PID / 日志 / 专用 profile，并只在任务结束或明确放弃后清理自己启动的实例；不要关闭用户提供的远程浏览器。
- 不要同时加载
references/cdp-direct.md 和 references/agent-browser.md。
flocks browser 的 daemon 文件固定放在 ~/.flocks/browser/，例如 bu.sock、bu.log、bu.pid、bu.port。
产品经验Skill
把特定产品页/网站的浏览器操作经验，沉淀到对应产品 skill，实现可复用。
适合沉淀的经验包括：
- 已确认某产品的稳定登录的方法
- 更稳定的页面进入方式，例如“优先直接拼 URL，不走菜单”
- 表格、筛选器、分页、弹窗、下载、详情展开等可靠操作路径
- 某站点特有的等待条件、重渲染特征、虚拟列表/SPA 交互怪癖
- 特定操作的成功经验，失败案例（特定操作失败 2 次以上，最终成功的经验）
具体怎么沉淀到 产品skill，请阅读 references/browser-experience-in-skill.md。
References
references/browser-experience-in-skill.md：如何把浏览器经验沉淀到产品 skill，以及推荐记录模板references/cdp-headless.md：cdp-headless 的全平台启动、连接与排障方式references/cdp-direct.md：以 flocks browser 作为 CDP 直连入口的启动方式、API、页面探索策略、错误处理references/agent-browser.md：agent-browser 的使用说明、错误处理等
