Adonis0123/adonis-skills / skills/chrome-dev-mcp
chrome-dev-mcp
VerifiedUse this skill when the user invokes /chrome-dev-mcp or asks for Chrome DevTools MCP, CDP, list_pages/select_page, UXC packaging for Chrome DevTools, DOM snapshots, Console, Network, Performance, Lighthouse, heap analysis, browser-internal debugging, connection recovery, or correct-Chrome validation across Claude Code, Codex, Grok Build/Grok002, Cursor CLI, Hermes, or WorkBuddy. Use it when the evidence is Chrome-specific (Lighthouse, a full trace, heap data) or the caller has no page session yet; a page already open in ego-browser keeps its own Console and request diagnosis. Also use it as the verification step right after the user or this session changes a web UI or asks to accept or check a page: collect a screenshot, Console, and Network evidence before calling it done. Do not use it for ordinary navigation, form filling, scraping, or desktop UI unless browser-internal signals or UI-change acceptance are required. A passing readiness or list_pages check proves the connection only, never the change.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.4 KB |
| evals/evals.json | config | 14.7 KB |
| evals/trigger-eval.json | config | 3.3 KB |
| references/host-verification.md | markdown | 5.9 KB |
| references/maintenance.md | markdown | 4.5 KB |
| references/profile-identity.md | markdown | 1.6 KB |
| references/uxc-facade.md | markdown | 7.5 KB |
| scripts/configure-local.zshexecutable | script | 1.8 KB |
| scripts/ensure-connection.zshexecutable | script | 2.6 KB |
| scripts/host-acceptance.zshexecutable | script | 6.9 KB |
| scripts/install-uxc.zshexecutable | script | 4.0 KB |
| scripts/lib/load-config.zshexecutable | script | 438 B |
| scripts/lib/readiness-envelope.zsh | script | 1.5 KB |
| scripts/lib/uxc-link-contract.zsh | script | 1.5 KB |
| scripts/lib/uxc-owned-binary.zsh | script | 2.8 KB |
| scripts/lib/uxc-release.zshexecutable | script | 642 B |
| scripts/setup-uxc-link.zshexecutable | script | 3.1 KB |
| scripts/test/host-acceptance.test.mjs | script | 5.3 KB |
| scripts/test/readiness-envelope.test.mjs | script | 2.7 KB |
| scripts/test/ui-acceptance.test.mjs | script | 5.2 KB |
| scripts/uxc-readiness.zshexecutable | script | 2.7 KB |
references/uxc-facade.md
View on GitHub# UXC stdio facade
Read this reference for the Chrome skill's default shared transport, installation ownership, and acceptance contract.
Use the `uxc-facade` skill for the generic decision and packaging contract. This reference contains only the Chrome-specific ownership, pin, link, and acceptance details.
## What UXC contributes
[UXC](https://github.com/holon-run/uxc) provides one discovery and invocation interface across OpenAPI, MCP, GraphQL, gRPC, and JSON-RPC. For MCP stdio, it can expose a fixed linked command, return a JSON envelope, and reuse the child session through its local daemon.
UXC is an adapter, not a browser or CDP implementation. In this skill it replaces eager per-host registration as the default execution path while preserving native registration only for explicit compatibility and rollback.
```text
managed chrome-dev-mcp-cli
-> pinned UXC daemon and one reusable stdio session
-> user-configured safe wrapper
-> identity-checked loopback Chrome
-> pinned chrome-devtools-mcp runtime
```
The safe wrapper validates its configured endpoint, WebSocket address, browser process, and intended profile before exposing the MCP runtime, and launches only the configured isolated profile when the endpoint is absent. Treat skill discovery, shared transport discovery, server handshake, tool discovery, endpoint identity, and a real tool call as separate layers; host-native MCP discovery is a compatibility-only layer.
## Why this skill keeps a separate contract
UXC also publishes a generic `chrome-devtools-mcp-skill` that favors package `@latest`, browser auto-connect, and optional fallbacks. Those defaults are useful for general discovery, but they do not prove a specific wrapper, runtime version, endpoint, or profile identity.
Keep this skill shared-first and fail-closed:
- disable eager native MCP registration host by host only after shared acceptance; preserve a documented rollback;
- link UXC only to the same safe wrapper; the main skill already forbids `@latest`, auto-connect, and automatic native fallback;
- treat sanitized readiness as shared transport evidence and the requested CLI operation as task acceptance.
## Reusable provenance
The pin lives in `scripts/lib/uxc-release.zsh` and currently records:
- official repository: `https://github.com/holon-run/uxc`;
- release: `v0.17.0`;
- official macOS release assets for Apple Silicon and Intel;
- SHA-256 digests published by the GitHub release;
- SHA-256 digests of the extracted binaries.
Run `scripts/install-uxc.zsh --manifest` to inspect the pins without downloading. The installer records the owner, release, platform, asset digest, and binary digest beside the installed binary. Later checks validate that private manifest and the pinned binary digest before executing `uxc`; an unowned binary, forged manifest, symlink, or digest mismatch fails closed.
Keep this installer with the Chrome skill; future UXC-backed skills should apply the `uxc-facade` contract and own their exact version, digest, platform policy, link, and acceptance helper because endpoint identity and safe output differ by service.
## Install, link, and validate
When upgrading the Chrome runtime, retain a recoverable pinned installation, inspect changed flags and filesystem defaults, and refresh only this endpoint's schema cache. Recreate the corresponding MCP child so the new version is actually loaded; report any interrupted in-flight calls. Keep Chrome itself running. Verify the fresh schema, two consecutive readiness calls, concurrent calls from different working directories, and an explicit-page operation on a disposable test page. Do not infer a speed improvement from a package version alone.
`scripts/install-uxc.zsh` owns the pinned binary and its manifest; `scripts/setup-uxc-link.zsh` owns the Chrome link; `scripts/uxc-readiness.zsh` owns both the payload-stripping readiness and the private-result task path. Never execute an unowned `uxc`, accept a PATH fallback, or overwrite a managed link whose exact contract differs.
When `chrome-dev-mcp-cli` is missing, run `zsh scripts/setup-uxc-link.zsh` only after confirming the pinned owned UXC binary is installed. It fails closed on a foreign link or binary.
After the user authorizes local installation:
1. Run `scripts/install-uxc.zsh`.
2. Run `scripts/setup-uxc-link.zsh`.
3. Run `zsh scripts/uxc-readiness.zsh` twice from the installed skill.
The first readiness call may create a daemon session and can spend up to 45 seconds attaching to a busy existing Chrome. The immediate second call should report `DAEMON_SESSION_REUSED=YES`. The helper discards the `list_pages` payload and prints only bounded status fields.
Those two calls are installation acceptance, not the readiness-plus-task fast path. When an invocation already includes a page task, run `zsh scripts/uxc-readiness.zsh --private-result` once instead. It applies the same owned binary/link and managed-`PATH` gates while retaining the one current-turn JSON result privately for target resolution.
Use a finite idle TTL so an unused MCP child is reaped. Treat the configured daemon-exclusive key as an ownership boundary, not session identity. Keep the fixed working directory in the managed launcher, not only in readiness, so UXC computes one stable session identity and calls from different projects reuse the same child (observed with the pinned 0.17.0; recheck after any UXC upgrade). The setup helper migrates only the exact legacy generated link and saves a recovery copy; it does not restart the daemon or browser.
## Concurrency details
- Chrome DevTools MCP 1.9.0+ (pinned 1.12.0) enables `--pageIdRouting` by default and restricts file writes to the OS temp directory unless `--workspace` is passed; older wrappers name the experimental flag. After an upgrade, confirm the live schema still requires `pageId` for page-scoped operations.
- Different page IDs route safely. Since 1.12.0 the runtime queues `page`-scoped tools (for example `wait_for`, `take_snapshot`, `take_screenshot`) per page; `exclusive` tools such as `evaluate_script`, performance traces, Lighthouse and heap snapshots still block the whole browser context. The pinned UXC 0.17.0 session still delivers calls one at a time: two concurrent 2.5-second `wait_for` calls took 5.1 seconds on different pages and on one page, the same as serial. Do not expect parallel execution through `chrome-dev-mcp-cli`; remeasure after a UXC upgrade. Use separate isolated browsers for parallel writes that cannot share a tab.
- Repair a known legacy launcher with `zsh scripts/setup-uxc-link.zsh`; it preserves the exact old owned link and refuses foreign contracts.
- The runtime's only file root is the MCP child's `os.tmpdir()` (on macOS `getconf DARWIN_USER_TEMP_DIR`), because UXC does not negotiate MCP workspace roots. If the host must render native content blocks, use explicit native compatibility mode.
Never log raw linked-command output for readiness `list_pages`. `STATUS=READY` proves shared transport and correct-browser attachment; verify each requested DevTools operation separately. Native-host acceptance is optional compatibility evidence, not the default success condition.
Discover exact parameters before calling a page-scoped operation:
```bash
chrome-dev-mcp-cli <operation> -h
chrome-dev-mcp-cli take_snapshot pageId=<fresh-numeric-page-id> filePath="$(getconf DARWIN_USER_TEMP_DIR)snapshot.txt"
```
Obtain the numeric page ID from the eligible current-turn private result, or refresh `list_pages` after recovery, navigation, or target ambiguity. Never copy a page ID from an earlier turn.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |