Chrome DevTools MCP Troubleshooting 是一个面向配置与连接问题的排查技能，扮演“配置和连接排障者”的角色。它的目标流程是：找到当前生效的 MCP 配置，定位确切的失败模式，然后只修改受影响测试环境的规范配置来源。
【用途与触发场景】 该技能用于审计 Chrome DevTools MCP 的安装与配置故障，包括服务器初始化失败、连接问题、页面列表异常、导航失败、工具缺失，以及 Chrome 配置文件错误等。触发时按参数分派：若未提供参数，则先询问出错的测试环境和确切错误；服务器初始化失败时，检查 MCP 配置、包可用性、Node 版本与启动参数；list_pages 或 new_page 失败时，排查连接模式、Chrome 配置文件与远程调试状态；工具缺失时，检查客户端只读模式、--slim 与扩展类别相关参数；配置文件错误或为空时，检查 user-data-dir、浏览器 URL、自动连接以及测试环境沙箱设置；扩展工具缺失时，检查扩展类别支持情况，以及 Chrome 是被启动还是被附加。
【排查步骤】 第一步：查找配置。在向用户索要内容前，先在测试环境常见的配置位置中检索，例如 .mcp.json、mcp.json、.vscode/mcp.json、.claude/settings.json、.gemini/settings.json 以及各测试环境的全局 MCP 配置。重点查看：包名或命令是否正确、参数是否拼写错误、必需的环境变量是否缺失、是否存在冲突的启动模式（如 --autoConnect 与 --browserUrl）、配置是否相对本仓库规范来源 config/mcp-registry.json 产生了漂移。 第二步：按已知症状分类。出现 "Could not find DevToolsActivePort" 通常指向自动连接行为，需确认目标 Chrome 正在运行、所需处已启用远程调试、测试环境可访问 Chrome 进程；不要在没有证据的情况下贸然切换到 --browserUrl。配置文件为空或无页面，检查 MCP 服务器是否启动了全新配置文件而非使用预期配置文件，并核对 --user-data-dir 的拼写与路径。工具缺失，检查 MCP 客户端是否处于只读或计划模式、是否启用了 --slim、扩展工具是否需要扩展类别参数。扩展问题，确认扩展类别工具已启用；某些 Chrome 版本在附加到已有浏览器实例时无法加载扩展，可能需要通过 MCP 启动 Chrome。 第三步：诊断。只运行有边界的诊断命令，例如 npx -y chrome-devtools-mcp@latest --help。若需要更详细日志，使用明确的日志文件路径，避免直接输出大量日志。 第四步：给出修复方案。推荐最小的配置改动，并说明改动应落在规范仓库来源、生成的项目表面、全局合并表面还是仅在 UI 中手动设置。保留 AGENTS.md 与 instructions/opencode-global.md 中记录的仓库特有约定。
【参考文件】 references/provenance.md 记录上游来源、提交、许可证与改编说明，在修改本技能或审计来源前阅读。
【关键规则】 提出修复建议前先阅读当前生效的 MCP 配置；若本仓库拥有该配置，应修改规范仓库来源而非生成的表面；除非被明确禁用或替换，保留 OpenCode 本地启动器覆盖；不要在没有匹配确切失败模式的情况下建议改动 --browserUrl 或 --autoConnect；使用有边界的诊断并避免直接输出大量日志。
【词汇表】 MCP owner：为某个测试环境拥有一个服务器的插件、扩展、仓库 MCP 配置或手动 UI 设置。Generated surface：由仓库规范来源生成、不直接编辑的配置。Canonical source：应优先于生成配置被修改的仓库文件。Launch mode：Chrome DevTools MCP 的连接方式，如启动配置文件、浏览器 URL 或自动连接。
【验证约定】 在宣称技能改动完成前，运行 uv run wagents validate、uv run python skills/skill-creator/scripts/audit.py skills/chrome-devtools-troubleshooting 以及 uv run wagents package chrome-devtools-troubleshooting --dry-run。
【限制】 资料未提供适用的 MCP 客户端或测试环境完整清单、具体的 Node 版本要求、支持的操作系统、收费与价格信息，以及除上述症状外的其他限制，这些内容暂未提供。