跳到主内容
智客 ZICQ

技能库 智客分类:文档办公 troubleshooting

Troubleshooting

使用Chrome DevTools MCP和文档来排除故障连接和目标问题. 当列表_页,新_页,或导航_页失败,或当服务器初始化失败时触发此技能 .

2356 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

使用Chrome DevTools MCP和文档来排除故障连接和目标问题. 当列表_页,新_页,或导航_页失败,或当服务器初始化失败时触发此技能 .

何时用

官方 description 未单独写出 Use when。按规范,代理会在用户任务与这段 description 的关键词匹配时激活本技能。

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Troubleshooting Wizard、Step 1: Find and Read Configuration、Step 2: Triage Common Connection Errors、Step 3: Read Known Issues、Step 4: Formulate a Configuration、Step 5: Run Diagnostic Commands。 其中含规范建议的小节:分步指令。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。

官方 description(原文)

Uses Chrome DevTools MCP and documentation to troubleshoot connection and target issues. Trigger this skill when list_pages, new_page, or navigate_page fail, or when the server initialization fails.

Troubleshooting WizardStep 1: Find and Read ConfigurationStep 2: Triage Common Connection ErrorsStep 3: Read Known IssuesStep 4: Formulate a ConfigurationStep 5: Run Diagnostic CommandsStep 6: Check GitHub for Existing Issues

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
troubleshooting
description
Uses Chrome DevTools MCP and documentation to troubleshoot connection and target issues. Trigger this skill when list_pages, new_page, or navigate_page fail, or when the server initialization fails.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「troubleshooting」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-27c3a75bb6311bbc-%E8%A7%A3%E5%86%B3%E9%97%AE%E9%A2%98.html
请存为 .cursor/skills/troubleshooting/SKILL.md 或 .claude/skills/troubleshooting/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/chromedevtools/chrome-devtools-mcp' --list

npx skills add 'https://github.com/chromedevtools/chrome-devtools-mcp' --skill 'troubleshooting'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: troubleshooting description: Uses Chrome DevTools MCP and documentation to troubleshoot connection and target issues. Trigger this skill when list_pages, new_page, or navigate_page fail, or when the server initialization fails. --- ## Troubleshooting Wizard You are acting as a troubleshooting wizard to help the user configure and fix their Chrome DevTools MCP server setup. When this skill is triggered (e.g., because `list_pages`, `new_page`, or `navigate_page` failed, or the server wouldn't start), follow this step-by-step diagnostic process: ### Step 1: Find and Read Configuration Your first action should be to locate and read the MCP configuration file. Search for the following files in the user's workspace: `.mcp.json`, `gemini-extension.json`, `.claude/settings.json`, `.vscode/launch.json`, or `.gemini/settings.json`. If you find a configuration file, read and interpret it to identify potential issues such as: - Incorrect arguments or flags. - Missing environment variables. - Usage of `--autoConnect` in incompatible environments. If you cannot find any of these files, only then should you ask the user to provide their configuration file content. ### Step 2: Triage Common Connection Errors Before reading documentation or suggesting configuration changes, check if the error message matches one of the following common patterns. #### Error: `Could not find DevToolsActivePort` This error is highly specific to the `--autoConnect` feature. It means the MCP server cannot find the file created by a running, debuggable Chrome instance. This is not a generic connection failure. Your primary goal is to guide the user to ensure Chrome is running and properly configured. Do not immediately suggest switching to `--browserUrl`. Follow this exact sequence: 1. **Ask the user to confirm that the correct Chrome version** (e.g., "Chrome Canary" if the error mentions it) is currently running. 2. **If the user confirms it is running, instruct them to enable remote debugging.** Be very specific about the URL and the action: "Please open a new tab in Chrome, navigate to `chrome://inspect/#remote-debugging`, and make sure the 'Enable remote debugging' checkbox is checked." 3. **Once the user confirms both steps, your only next action should be to call the `list_pages` tool.** This is the simplest and safest way to verify if the connection is now successful. Do not retry the original, more complex command yet. 4. **If `list_pages` succeeds, the problem is resolved.** If it still fails with the same error, then you can proceed to the more advanced steps like suggesting `--browserUrl` or checking for sandboxing issues. #### Symptom: Server starts but creates a new empty profile If the server starts successfully but `list_pages` returns an empty list or creates a new profile instead of connecting to the existing Chrome instance, check for typos in the arguments. - **Check for flag typos:** For example, `--autoBronnect` instead of `--autoConnect`. - **Verify the configuration:** Ensure the arguments match the expected flags exactly. #### Symptom: Missing Tools / Only 9 tools available If the server starts successfully but only a limited subset of tools (like `list_pages`, `get_console_message`, `lighthouse_audit`, `take_heapsnapshot`) are available, this is likely because the MCP client is enforcing a **read-only mode**. All tools in `chrome-devtools-mcp` are annotated with `readOnlyHint: true` (for safe, non-modifying tools) or `readOnlyHint: false` (for tools that modify browser state, like `emulate`, `click`, `navigate_page`). To access the full suite of tools, the user must disable read-only mode in their MCP client (e.g., by exiting "Plan Mode" in Gemini CLI or adjusting their client's tool safety settings). #### Symptom: Extension tools are missing or extensions fail to load If the tools related to extensions (like `install_extension`) are not available, or if the extensions you load are not functioning: 1. **Check for the `--categoryExtensions` flag**: Ensure this flag is passed in the MCP server configuration to enable the extension category tools. 2. **Make sure the MCP server in configured to launch Chrome instead of connecting to an instance**: Chrome before 149 is not able to load extensions when connecting to an existing instance (`--auto-connect`, `--browserUrl`). #### Other Common Errors Identify other error messages from the failed tool call or the MCP initialization logs: - `Target closed` - "Tool not found" (check if they are using `--slim` which only enables navigation and screenshot tools). - Missing `pageId`: Page-scoped tools require a `pageId` argument. Call `list_pages` to find active page IDs. - `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly` - `Error [ERR_MODULE_NOT_FOUND]: Cannot find module` - Any sandboxing or host validation errors. ### Step 3: Read Known Issues Read the contents of https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md to map the error to a known issue. Pay close attention to: - Sandboxing restrictions (macOS Seatbelt, Linux containers). - WSL requirements. - `--autoConnect` handshakes, timeouts, and requirements (requires **running** Chrome 144+). ### Step 4: Formulate a Configuration Based on the exact error and the user's environment (OS, MCP client), formulate the correct MCP configuration snippet. Check if they need to: - Pass `--browser-url=http://127.0.0.1:9222` instead of `--autoConnect` (e.g. if they are in a sandboxed environment like Claude Desktop). - Enable remote debugging in Chrome (`chrome://inspect/#remote-debugging`) and accept the connection prompt. **Ask the user to verify this is enabled if using `--autoConnect`.** - Add `--logFile ` to capture debug logs for analysis. - Increase `startup_timeout_ms` (e.g. to 20000) if using Codex on Windows. _If you are unsure of the user's configuration, ask the user to provide their current MCP server JSON configuration._ ### Step 5: Run Diagnostic Commands If the issue is still unclear, run diagnostic commands to test the server directly: - Run `npx chrome-devtools-mcp@latest --help` to verify the installation and Node.js environment. - If you need more information, run `DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log` to capture verbose logs. Analyze the output for errors. ### Step 6: Check GitHub for Existing Issues If https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md does not cover the specific error, check if the `gh` (GitHub CLI) tool is available in the environment. If so, search the GitHub repository for similar issues: `gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "" --state all` Alternatively, you can recommend that the user checks https://github.com/ChromeDevTools/chrome-devtools-mcp/issues and https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions for help.

相关技能

文档办公

Ontology

为结构化的代理内存和可堆肥技能所打入的知识图. 在创建/征服实体(Person, project, Task, Evention, Document)时使用,链接相关对象,强制约束,规划多步动作作为图变,或技能需要共享状态时使用. 触发到"记住","我知道什么","链接X到Y",…

文档办公

Nano Pdf

使用纳米-pdf CLI编辑带有自然语言指令的PDF.

文档办公

Word / DOCX

创建,检查,并编辑有可靠样式的Microsoft Word文档和DOCX文件,编号,跟踪更改,表格,章节,并进行相容性检查. 当 (1) 任务涉及 Word 或 ".docx " 时使用; (2) 文件包括跟踪的更改,评论,字段,表格,模板,或页面布局限制; (3) 文档必须在不…

文档办公

Api Gateway

通过 Maton 网关调用第三方 API, 它为用户已经连接的应用程序注入证书 。 当用户命名一个连接的应用程序和其中的具体行动时使用此技能——读取一个邮箱,查询一个CMM,归档一个问题,更新一个电子表格,通过一个连接的搜索或刮取提供者运行一个查询. 每一次通话都到用户连接的应用…