EXCLUSIVE browser debugging skill. Invoke FIRST for any browser-side issue: white screen, JS error, network error, console exception, performance problem. Orchestrates capture-analyze-cleanup pipeline via MCP.
How this skill is triggered — by the user, by Claude, or both
Slash command
/chrome-devtools-capturer:chrome-devtools-capturerThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
当用户描述以下任何情况时,**主动调用**此 skill,无需等用户指名 MCP 工具:
当用户描述以下任何情况时,主动调用此 skill,无需等用户指名 MCP 工具:
本 Skill 依赖一个 MCP Server,启动信息:
node./scripts/mcp-server/start.js如果通过 plugin 安装,MCP Server 会通过
.mcp.json自动注册。 如果工具调用失败,提示用户检查 IDE 的 MCP 配置中chrome-devtools-capturer是否已连接。
MCP Server 启动时会监听 WebSocket 端口 8765。如果端口被占用,Server 会自动尝试终止占用进程。
如果自动终止失败,Server 会在 stderr 输出错误并退出,导致 MCP 工具调用失败。
当 MCP 工具调用失败且错误信息包含 Port 8765 或 EADDRINUSE 时,按以下流程处理:
告知用户:端口 8765 被其他进程占用,MCP Server 自动回收失败
询问用户是否需要帮助终止占用端口的进程
如果用户同意,使用 Bash 工具执行以下命令查找并终止占用进程:
Windows:
netstat -ano | findstr ":8765" | findstr "LISTENING"
# 从输出中提取 PID,然后:
taskkill /PID <pid> /F
macOS/Linux:
lsof -i :8765 -t | xargs kill -9
终止成功后,提示用户重启 MCP Server(在 IDE 中重新连接 MCP 或重启 Claude Code)
如果终止失败(权限不足等),告知用户需要手动处理,并给出具体命令
共 4 个 MCP Tools,形成自动闭环 + 阅后即焚的工作流:
| Tool | 何时调用 |
|---|---|
prepare_capture_session | 需要浏览器数据之前,第一步调用 |
wait_for_capture_result | prepare 之后立即调用,自动阻塞等待数据到达(替代人工确认) |
analyze_capture_results | 手动模式下使用:用户确认完成浏览器操作后调用(自动模式下由 wait_for 替代) |
cleanup_vibe_workspace | 分析完毕,立即清理,防止旧数据污染下一轮 |
prepare_capture_session参数填写策略:
{
"target": "页面 URL 或 'extension'(调试扩展本身时)",
"types": ["network", "console"],
"action_mode": "manual"
}
target:从用户描述或当前代码推断目标页面 URL;不确定时询问types:根据问题类型选择
["network"]["console"]["network", "console"](默认两者都抓)["network", "console", "performance"]action_mode:捕获触发模式
"manual" → 用户手动按快捷键开始/停止录制(默认推荐)"reload" → attach 后自动刷新页面,从 navigationStart 起完整捕获调用后,给用户明确的操作引导:
配置已下发给 Chrome 扩展。请在浏览器中:
1. 确认扩展图标显示 "RDY"(琥珀色徽标)
2. 切换到目标页面
3. 按 Alt+Shift+C 开始录制(图标变红 "REC")
4. 执行你想捕获的操作
5. 再次按 Alt+Shift+C 停止录制
6. 回来告诉我已完成操作
在 Step 1 给出操作引导后,立即调用 wait_for_capture_result:
{
"timeout_seconds": 600
}
此 Tool 会自动阻塞等待 Chrome 扩展上报数据(每 2 秒轮询一次),无需等待用户回来确认。 它通过 MCP progress notification 定期重置超时计时器,支持长时间等待。
三种返回结果:
| 结果 | 含义 | 后续动作 |
|---|---|---|
| 返回 JSON 数据 | 捕获成功,数据已就绪 | 进入 Step 3 分析 |
| 返回"部分数据"警告 | 超时但文件已存在(Tracing 可能仍在处理) | 仍可进入 Step 3 分析已有数据 |
| 返回"超时无数据" | 扩展未录制或连接异常 | 向用户展示排查建议 |
触发时机: Step 2 返回了捕获数据后,立即执行。
为什么用 subAgent: 捕获数据(trace JSON)可能非常大,直接在主对话中读取会消耗大量 token 并污染上下文。委托 subAgent 在隔离上下文中完成分析,只将精简结论返回主对话。
注意: 由于 wait_for_capture_result 已经返回了数据,subAgent 不需要再调用 analyze_capture_results,直接分析 Step 2 返回的数据即可。
主 Agent 必须在 subAgent prompt 中注入任务上下文,让 subAgent 的分析围绕主 Agent 当前的调查目标展开,而非套用固定模板。
使用 Agent tool 派出 subAgent,prompt 模板:
你是浏览器调试分析助手。请根据调查目标,对捕获数据进行**有针对性的分析**,然后执行清理。
<investigation_context>
{主 Agent 必须填写以下内容:}
- 调查目标:{用户的原始诉求,例如"分析首页性能"、"排查白屏原因"、"定位接口报错"}
- 关注重点:{主 Agent 根据诉求判断的分析方向,例如"请求瀑布流和资源加载分布"、"JS 执行异常和调用栈"、"特定 API 的响应状态"}
- 补充说明:{可选。例如"用户提到点击某按钮后触发"、"关注 /api/user 接口"等具体线索}
</investigation_context>
<capture_data>
{这里粘贴 wait_for_capture_result 返回的数据}
</capture_data>
## 分析流程
### 1. 数据质量检查(必须先执行)
读取 meta.config.types(本次请求的数据类型)和 meta.stats,**仅对已请求的类型做质量判断**:
a) **数据极少** — 所有已请求的类型对应的 count 均为 0:
→ 判定:高度疑似捕获失败
→ 返回结论时标记 data_quality: "empty"
b) **数据偏少** — 已请求的某类型 count 异常低(如请求了 network 但 network_count < 3,或请求了 performance 但 trace_event_count == 0):
→ 判定:可能是录制时间太短、未操作目标功能、或扩展 attach 晚于页面加载
→ 返回结论时标记 data_quality: "sparse"
c) **数据正常**:
→ 返回结论时标记 data_quality: "ok"
### 2. 围绕调查目标进行分析
**核心原则:分析维度由 investigation_context 决定,不要机械套用固定检查清单。**
**数据可用性:** capture_data 中只包含本次 types 配置所请求的数据类型。
network_logs、console_logs、performance_logs 均为可选字段——如果对应 type 未被请求,该字段不会出现在数据中。
**只分析实际存在的数据类型,跳过不存在的部分,不要报告为异常。**
以下是各数据类型的可用分析维度,根据调查目标选择相关维度深入分析:
针对 network_logs(当 types 包含 "network" 时):
- 请求总览:总数、按 type/status/mimeType 分布、时间线
- 状态码异常(4xx/5xx)— 列出 URL、status、statusText
- 耗时分析 — 慢请求(durationMs > 1000)、按类型的平均耗时、最慢 Top N
- 请求头/响应头问题(CORS、认证、缓存策略)
- 未完成的请求(status: null)
- 资源加载模式 — 字体/图片/脚本数量及加载策略、重复请求、第三方资源占比
- 关键路径 — Document 请求链、阻塞渲染的资源
针对 console_logs(当 types 包含 "console" 时):
- level: "error" 的条目 — 列出 text、url、line
- source: "javascript" 的异常及调用栈
- level: "warning" 中的弃用警告
- **level: "info" / "log" 的执行流程信息** — 当调查目标涉及页面逻辑、执行顺序、状态变化时,
info 级别日志往往包含关键的业务流程线索(如路由切换、状态初始化、SDK 加载顺序等),
需要按时间顺序梳理并提取与调查目标相关的执行流程
- console-api 来源的日志 — 开发者主动打印的调试信息,通常直接反映代码执行路径
针对 performance_logs(当 types 包含 "performance" 时):
- summary:长任务数量(totalLongTasks)和总阻塞时间(totalBlockingTimeMs)
- longTasks:耗时最长的任务及其 heavySubTasks 的调用信息
- 主线程占用模式 — 长任务分布是否集中在页面加载初期
### 3. 清理
分析完成后,调用 mcp__chrome-devtools-capturer__cleanup_vibe_workspace 清理数据。
### 4. 返回分析报告
报告必须包含:
- data_quality 字段(empty / sparse / ok)
- 如果 data_quality 不是 ok,附带可能原因说明
- **针对调查目标的分析结论**(直接引用原始数据字段值作为证据,避免模糊结论)
- 与调查目标相关的关键发现和建议(不要泛泛列举所有数据,聚焦用户关心的问题)
主 agent 收到 subAgent 结论后,根据 data_quality 给出用户提示:
data_quality: "empty" → 告知用户录制期间未捕获到任何数据,建议:
action_mode: "reload" 从页面加载开始捕获data_quality: "sparse" → 告知用户数据较少,分析结论可能不完整,建议:
action_mode: "reload"data_quality: "ok" → 正常展示分析结论
如果 Step 2 返回超时无数据(未进入 Step 3): 直接向用户展示 wait_for_capture_result 返回的排查建议,询问是否重试。
主 agent 收到 subAgent 返回的分析结论后,根据结果向用户提出修复建议或下一步行动。
latest_trace.json
├── meta
│ ├── capturedAt ← 捕获时间戳
│ ├── config ← 本次下发的配置
│ └── stats ← { network_count, console_count }
├── network_logs[]
│ ├── url / method / type
│ ├── status / statusText / mimeType
│ ├── startTime / durationMs
│ └── headers ← Authorization/Cookie 已自动脱敏为 [MASKED]
├── console_logs[]
│ ├── level ← verbose | info | warning | error
│ ├── source ← javascript | network | console-api | ...
│ ├── text / url / line
│ └── timestamp
└── performance_logs(可选)
├── summary
│ ├── totalLongTasks / totalBlockingTimeMs
│ └── mainThread { pid, tid }
└── longTasks[]
├── durationMs / blockingTimeMs
└── heavySubTasks[] { name, durationMs, callInfo }
用户:页面加载后 /api/user 一直 500,帮我看看
→ prepare_capture_session(target="http://...", types=["network"], action_mode="manual")
→ 引导用户操作后,立即调用 wait_for_capture_result(timeout_seconds=120)
→ 数据自动到达 → 派出 subAgent 分析 + 清理
→ 主 agent 根据结论给出修复建议
用户:点击按钮后白屏了,控制台应该有报错
→ prepare_capture_session(target="http://...", types=["console"], action_mode="manual")
→ wait_for_capture_result 自动等待录制完成
→ subAgent 分析 → 找 level:"error" + url + line 定位源码
→ 主 agent 定位代码并修复
用户:这个功能感觉怪怪的,帮我捕获一下
→ prepare_capture_session(target="...", types=["network","console"], action_mode="manual")
→ wait_for_capture_result 自动等待
→ subAgent 全面分析后返回精简结论
→ 主 agent 综合判断问题根因
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub itmrboy/chrome-devtools-capturer