@e4779/skills 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/chrome-devtools/README.md +76 -0
- package/chrome-devtools/SKILL.md +277 -0
- package/chrome-devtools/references/recipes.md +379 -0
- package/chrome-devtools/references/setup.md +138 -0
- package/drawio/SKILL.md +395 -0
- package/gh-cli/SKILL.md +83 -0
- package/grill/SKILL.md +72 -0
- package/layout-check/README.md +32 -0
- package/layout-check/SKILL.md +416 -0
- package/layout-check/scripts/layoutProbe.mjs +539 -0
- package/mcpls/SKILL.md +261 -0
- package/mcpls/references/configuration.md +131 -0
- package/mcpls/references/install.md +13 -0
- package/mcporter/SKILL.md +90 -0
- package/mindmap/SKILL.md +46 -0
- package/mindmap/references/drawio-recipe.md +60 -0
- package/mindmap/references/mindmap-design.md +63 -0
- package/opensource-contribution/SKILL.md +119 -0
- package/package.json +33 -5
- package/shell-taste/.shellcheckrc +16 -0
- package/shell-taste/SKILL.md +95 -0
- package/shell-taste/references/handbook/dialects.md +168 -0
- package/shell-taste/references/handbook/dom/01-output-logging.md +245 -0
- package/shell-taste/references/handbook/dom/02-errors-exit.md +48 -0
- package/shell-taste/references/handbook/dom/03-installation-setup.md +179 -0
- package/shell-taste/references/handbook/dom/04-network.md +384 -0
- package/shell-taste/references/handbook/dom/05-files-paths.md +74 -0
- package/shell-taste/references/handbook/dom/06-checks-validation.md +127 -0
- package/shell-taste/references/handbook/dom/07-system-administration.md +103 -0
- package/shell-taste/references/handbook/dom/08-privilege-users.md +58 -0
- package/shell-taste/references/handbook/dom/09-text-data.md +62 -0
- package/shell-taste/references/handbook/dom/10-terminal-ux.md +60 -0
- package/shell-taste/references/handbook/dom/11-process-control.md +28 -0
- package/shell-taste/references/handbook/dom/12-uncategorized.md +161 -0
- package/shell-taste/references/handbook/dom/13-containers.md +13 -0
- package/shell-taste/references/handbook/dom/14-agents-ai-tooling.md +13 -0
- package/shell-taste/references/handbook/family-index.md +230 -0
- package/shell-taste/references/handbook/index.md +41 -0
- package/skill-author/SKILL.md +86 -0
- package/sobesednik/SKILL.md +98 -0
- package/sobesednik/card-template.md +23 -0
- package/sobesednik/personas/advocate.md +27 -0
- package/sobesednik/personas/analyst.md +29 -0
- package/sobesednik/personas/chat.md +42 -0
- package/sobesednik/personas/ifs.md +32 -0
- package/sobesednik/personas/journal/README.md +6 -0
- package/sobesednik/personas/nasreddin.md +29 -0
- package/sobesednik/personas/premortem.md +29 -0
- package/sobesednik/personas/rogers.md +27 -0
- package/sobesednik/personas/socratic.md +29 -0
- package/sobesednik/personas/stoic.md +27 -0
- package/sobesednik/references/persona-design.md +41 -0
- package/zai-mcp/README.md +63 -0
- package/zai-mcp/SKILL.md +160 -0
- package/zai-mcp/references/recipes.md +273 -0
- package/zai-mcp/references/tools.md +266 -0
- package/README.md +0 -3
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# chrome-devtools skill
|
|
2
|
+
|
|
3
|
+
Drive a real Windows Chrome tab from a pi agent in WSL via the
|
|
4
|
+
`chrome-devtools` MCP — as **fabric natives** (`mcp.chrome_devtools.*` inside
|
|
5
|
+
`fabric_exec`), without the ~18k-token schema bloat that MCP tool listings dump
|
|
6
|
+
into context.
|
|
7
|
+
|
|
8
|
+
Instead of exposing all 29 tools through full MCP listings (every tool
|
|
9
|
+
description sits in the system prompt every turn), this skill teaches the agent
|
|
10
|
+
the few calls and workflows it actually needs. The full surface is reachable
|
|
11
|
+
on demand via `tools.describe({ ref: "mcp.chrome_devtools.<tool>" })` — live and
|
|
12
|
+
always current — and worked recipes load **on demand** from `references/`.
|
|
13
|
+
|
|
14
|
+
## Architecture (WSL → Windows Chrome)
|
|
15
|
+
|
|
16
|
+
Two Windows Chrome instances, driven from WSL over mirrored networking
|
|
17
|
+
(`127.0.0.1` shared between both sides):
|
|
18
|
+
|
|
19
|
+
| server | Chrome | port | use |
|
|
20
|
+
|---|---|---|---|
|
|
21
|
+
| `chrome-devtools` | direct instance | 9222 | default — real rendering |
|
|
22
|
+
| `chrome-devtools-proxy` | proxied instance | 9223 | blocked (foreign) sites via bypass proxy |
|
|
23
|
+
|
|
24
|
+
Both mapped in `~/.mcporter/mcporter.json` to
|
|
25
|
+
`--browserUrl http://127.0.0.1:922X`; fabric discovers them from there.
|
|
26
|
+
|
|
27
|
+
Verify inside any `fabric_exec`:
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
await mcp.chrome_devtools.list_pages({});
|
|
31
|
+
await tools.call({ ref: "mcp.$servers" });
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## What it does
|
|
35
|
+
|
|
36
|
+
- Browser automation & scraping (navigate, snapshot, click, fill forms)
|
|
37
|
+
- Front-end debugging (console errors, network requests, computed styles)
|
|
38
|
+
- UI verification after code changes (snapshot diff, screenshots)
|
|
39
|
+
- Performance measurement (Core Web Vitals, traces)
|
|
40
|
+
|
|
41
|
+
All as native calls inside `fabric_exec`; the `mcporter call` CLI remains a
|
|
42
|
+
break-glass fallback.
|
|
43
|
+
|
|
44
|
+
## Structure
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
chrome-devtools/
|
|
48
|
+
├── SKILL.md # always-on: when to use + top tools + workflow
|
|
49
|
+
├── README.md # this file (for humans)
|
|
50
|
+
└── references/
|
|
51
|
+
├── setup.md # first-run setup guide (load on demand)
|
|
52
|
+
└── recipes.md # worked end-to-end scenarios (load on demand)
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The recipes in `references/recipes.md` are drawn from real scraping sessions
|
|
56
|
+
(finam.ru, MOEX, dohod.ru, ЦБ РФ, FRED — ~1300 recorded calls), not invented
|
|
57
|
+
examples.
|
|
58
|
+
|
|
59
|
+
## Token economics
|
|
60
|
+
|
|
61
|
+
| Approach | Tokens in system prompt (every turn) |
|
|
62
|
+
|---|---|
|
|
63
|
+
| Full MCP tool listings (chrome-devtools) | ~18 000 |
|
|
64
|
+
| This skill (SKILL.md only) | ~1 500 |
|
|
65
|
+
| On-demand `tools.describe` per tool | ~200 (one-shot) |
|
|
66
|
+
|
|
67
|
+
## Related
|
|
68
|
+
|
|
69
|
+
- **`chrome-css`** skill (in `pi-design-skill`) — ready-made `evaluate_script` patterns for `getComputedStyle` / box model
|
|
70
|
+
- **`layout-check`** skill (in this repo) — coordinate-table layout verification; pair with screenshots for visual regressions
|
|
71
|
+
- Upstream MCP: [ChromeDevTools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp)
|
|
72
|
+
- MCP runtime config: `~/.mcporter/mcporter.json` (mcporter format, consumed by fabric)
|
|
73
|
+
|
|
74
|
+
## License
|
|
75
|
+
|
|
76
|
+
ISC
|
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: chrome-devtools
|
|
3
|
+
description: >
|
|
4
|
+
Drive a real Chrome tab via the chrome-devtools MCP. Use when the user asks
|
|
5
|
+
to scrape a website, test a frontend, click buttons, fill out or submit
|
|
6
|
+
forms, log in, debug console errors, inspect network requests, take page
|
|
7
|
+
screenshots, or measure page performance. Workflow: navigate, take a11y
|
|
8
|
+
snapshots (every element gets a uid), click/fill/hover via uid, evaluate
|
|
9
|
+
JS, read console & network, capture screenshots, run performance traces.
|
|
10
|
+
Call `mcp.chrome_devtools.*` inside `fabric_exec` — type-checked, no CLI spawn.
|
|
11
|
+
RU: заскрейпить сайт, потестировать фронтенд, заполнить форму, скриншот страницы, ошибки консоли, запросы сети.
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# Chrome DevTools
|
|
15
|
+
|
|
16
|
+
Drive a real Chrome tab through the `chrome-devtools` MCP via Fabric's `mcp.*`
|
|
17
|
+
surface. All calls are type-checked TypeScript inside `fabric_exec` — no
|
|
18
|
+
`mcporter call` CLI, no process spawn.
|
|
19
|
+
|
|
20
|
+
## WSL → Windows Chrome (mirrored networking)
|
|
21
|
+
|
|
22
|
+
Desktop Chrome binds CDP to loopback only — `--remote-debugging-address` is
|
|
23
|
+
silently ignored (verified on Chrome 151). So from WSL, drive the *Windows*
|
|
24
|
+
Chrome via mirrored networking, where `127.0.0.1` is shared between both:
|
|
25
|
+
|
|
26
|
+
- `C:\Users\e41q\.wslconfig` → `[wsl2] networkingMode=mirrored` (applies
|
|
27
|
+
after `wsl --shutdown`).
|
|
28
|
+
- Launch (from Windows or via interop — see below): `chrome-debug.ps1` →
|
|
29
|
+
port **9222** direct; `chrome-debug-proxy.ps1` → port **9223** through the
|
|
30
|
+
bypass proxy `<proxy-host>:8888` (profile `chrome-mb-profile`,
|
|
31
|
+
anti-automation-detection flags). Both live in `C:\Users\e41q\.local\bin\`.
|
|
32
|
+
- WSL `~/.mcporter/mcporter.json` maps `chrome-devtools` /
|
|
33
|
+
`chrome-devtools-proxy` to `--browserUrl http://127.0.0.1:922X`.
|
|
34
|
+
- Interop: the agent can spawn/kill Windows Chrome straight from WSL —
|
|
35
|
+
`powershell.exe -NoProfile -Command "$p = Start-Process ... -PassThru; $p.Id"`
|
|
36
|
+
captures the PID; `taskkill.exe /PID <pid> /T /F` cleans up.
|
|
37
|
+
- Verify: `curl -s http://127.0.0.1:9222/json/version`.
|
|
38
|
+
|
|
39
|
+
Two instances = two windows on the Windows desktop: watch the direct one for
|
|
40
|
+
real rendering, the proxied one for blocked-site work.
|
|
41
|
+
|
|
42
|
+
Proxy discipline (never open RU domains through 9223 — detection exposure) lives in
|
|
43
|
+
the GLOBAL `~/.pi/agent/AGENTS.md`, not here: it applies to every tool, not
|
|
44
|
+
just this skill.
|
|
45
|
+
|
|
46
|
+
Cold start of the mb-profile instance may restore many tabs and wedge early
|
|
47
|
+
MCP calls for a minute or two; if `list_pages` hangs, wait for the profile to
|
|
48
|
+
settle or restart the instance.
|
|
49
|
+
|
|
50
|
+
## Prerequisites
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
// Smoke test — list pages (first call may time out on cold start, see Troubleshooting)
|
|
54
|
+
await mcp.chrome_devtools.list_pages({});
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Missing or broken? See `<skill-dir>/references/setup.md` (inventory → repair →
|
|
58
|
+
smoke test).
|
|
59
|
+
|
|
60
|
+
## When to use
|
|
61
|
+
|
|
62
|
+
- Browser automation / scraping, front-end debugging, UI verification after code changes.
|
|
63
|
+
- Any task where you'd reach for Playwright/Puppeteer.
|
|
64
|
+
|
|
65
|
+
**Don't** use it for static HTML — `pi.read` the file. Chrome is for *live* /
|
|
66
|
+
JS-rendered pages.
|
|
67
|
+
|
|
68
|
+
## Core workflow
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
list_pages → select_page → navigate_page → take_snapshot → (act) → verify
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### ⚠️ Seven times measure, once cut — check the schema before you call
|
|
75
|
+
|
|
76
|
+
> The stupidest question is the one you didn't ask. `tools.describe` is free,
|
|
77
|
+
> hallucinated args are not. A 2-second check beats a 20-minute debugging detour.
|
|
78
|
+
|
|
79
|
+
Before using **any** tool you haven't called in this session, check its live
|
|
80
|
+
schema — it is always more current than any static doc:
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
// One call, full schema: types, enums, defaults, required fields
|
|
84
|
+
await tools.describe({ ref: "mcp.chrome_devtools.take_screenshot" });
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Do this especially after updating the MCP package — tools are added/renamed
|
|
88
|
+
between versions. The schema is the source of truth; this skill documents only
|
|
89
|
+
what the schema *cannot* tell you (gotchas, pi-specific wiring, behavioral traps).
|
|
90
|
+
|
|
91
|
+
1. **`take_snapshot`** is your eyes — the a11y tree with a `uid` per element.
|
|
92
|
+
Prefer it over `take_screenshot` (text is cheaper and more precise than pixels).
|
|
93
|
+
2. **`uid`** from the snapshot addresses elements in `click` / `fill` / `hover`.
|
|
94
|
+
Only a11y-tree elements get a uid — a plain `<span>` (even with `aria-label`)
|
|
95
|
+
is invisible. Give decorative icons `role="img"` (or `role="button"`) so they
|
|
96
|
+
can be targeted — this is also correct a11y.
|
|
97
|
+
3. After any action, re-snapshot — the uid prefix changes with EVERY new
|
|
98
|
+
snapshot (not only on DOM change), so never reuse uids from an old snapshot.
|
|
99
|
+
Pass `includeSnapshot: true` on click/fill to get the fresh tree in the same call.
|
|
100
|
+
|
|
101
|
+
### ⚠️ Use the semantic tool, not `evaluate_script`
|
|
102
|
+
|
|
103
|
+
`evaluate_script` is for **reading** state (DOM, styles, text, tables). For
|
|
104
|
+
**actions** — click, fill, scroll, hover — it is the *wrong* tool: slower (no
|
|
105
|
+
`includeSnapshot`), brittle (skips real event listeners), harder to debug.
|
|
106
|
+
|
|
107
|
+
| Want to… | ❌ Don't | ✅ Do |
|
|
108
|
+
|---|---|---|
|
|
109
|
+
| Click a button/link | `el.click()` in evaluate_script | `click({ uid: "1_5" })` |
|
|
110
|
+
| Type into a field | `el.value = 'x'` | `fill({ uid: "1_7", value: "x" })` |
|
|
111
|
+
| Fill a form | multiple `fill`s | `fill_form({ elements: [...] })` |
|
|
112
|
+
| Scroll the page | `window.scrollTo(...)` | `press_key({ key: "End" })` |
|
|
113
|
+
| Submit a form | `form.submit()` | `click` the submit button |
|
|
114
|
+
| Hover for a tooltip/menu | `dispatchEvent(...)` | `hover({ uid: "1_3" })` |
|
|
115
|
+
| Read N items / styles / text | — | **`evaluate_script` is correct here** |
|
|
116
|
+
|
|
117
|
+
## Top tools
|
|
118
|
+
|
|
119
|
+
All calls are `mcp.chrome_devtools.<tool>(args)` inside `fabric_exec`.
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
// Navigate — all page tools require pageId (get it from list_pages)
|
|
123
|
+
await mcp.chrome_devtools.navigate_page({ pageId: 1, type: "url", url: "https://example.com" });
|
|
124
|
+
await mcp.chrome_devtools.new_page({ url: "https://example.com" });
|
|
125
|
+
await mcp.chrome_devtools.navigate_page({ pageId: 1, type: "reload", ignoreCache: true });
|
|
126
|
+
|
|
127
|
+
// See — snapshot (a11y tree, primary view) or screenshot (colors/layout)
|
|
128
|
+
await mcp.chrome_devtools.take_snapshot({ pageId: 1 });
|
|
129
|
+
await mcp.chrome_devtools.take_snapshot({ pageId: 1, verbose: true });
|
|
130
|
+
const tmp = (await pi.bash({ cmd: "node -e 'console.log(require(\"os\").tmpdir())'" })).output.trim();
|
|
131
|
+
await mcp.chrome_devtools.take_screenshot({ pageId: 1, filePath: `${tmp}/page.png` });
|
|
132
|
+
|
|
133
|
+
// Interact (need a uid from a snapshot)
|
|
134
|
+
await mcp.chrome_devtools.click({ pageId: 1, uid: "1_5", includeSnapshot: true });
|
|
135
|
+
await mcp.chrome_devtools.fill({ pageId: 1, uid: "1_7", value: "hello" });
|
|
136
|
+
await mcp.chrome_devtools.fill_form({ pageId: 1, elements: [{ uid: "1_7", value: "user" }, { uid: "1_8", value: "pass" }] });
|
|
137
|
+
await mcp.chrome_devtools.hover({ pageId: 1, uid: "1_3" });
|
|
138
|
+
await mcp.chrome_devtools.press_key({ pageId: 1, key: "Enter" });
|
|
139
|
+
await mcp.chrome_devtools.wait_for({ pageId: 1, text: ["Welcome", "Error"] });
|
|
140
|
+
|
|
141
|
+
// Evaluate JS — read state, returns JSON.
|
|
142
|
+
// No `awaitPromise` argument (that's the Playwright API — it is rejected);
|
|
143
|
+
// to wait, RETURN a promise from the function; it will be awaited.
|
|
144
|
+
// Valid args: pageId, function, args, filePath, dialogAction, waitForStableDom.
|
|
145
|
+
await mcp.chrome_devtools.evaluate_script({ pageId: 1, function: "() => document.title" });
|
|
146
|
+
await mcp.chrome_devtools.evaluate_script({ pageId: 1, function: '() => fetch("/api/x").then(r => r.json()).then(j => ({ total: j.totalCount }))' });
|
|
147
|
+
|
|
148
|
+
// Pages
|
|
149
|
+
await mcp.chrome_devtools.list_pages({});
|
|
150
|
+
await mcp.chrome_devtools.select_page({ pageId: 2 });
|
|
151
|
+
await mcp.chrome_devtools.close_page({ pageId: 2 });
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## Screenshots — where to save & how to read
|
|
155
|
+
|
|
156
|
+
> **Prefer `take_snapshot` for verification** — the a11y tree text is cheaper, more precise,
|
|
157
|
+
> and doesn't need a vision-capable model. Use screenshots only when you need to see
|
|
158
|
+
> colors/layout/visual regressions.
|
|
159
|
+
|
|
160
|
+
`take_screenshot` writes to `filePath`. **The path must be inside an allowed
|
|
161
|
+
workspace root**, otherwise you get `Access denied: path … is not within any of
|
|
162
|
+
the configured workspace roots`.
|
|
163
|
+
|
|
164
|
+
### Where to save — `os.tmpdir()` is the ONLY root by default
|
|
165
|
+
|
|
166
|
+
`chrome-devtools-mcp` (v1.12.0+) sets `DEFAULT_FILESYSTEM_ROOT = [os.tmpdir()]`.
|
|
167
|
+
That is the **only** workspace root unless the server is launched with
|
|
168
|
+
`--workspace=<path>`. The MCP `roots` capability from the client is ignored
|
|
169
|
+
in practice. Consequence per OS:
|
|
170
|
+
|
|
171
|
+
| OS | `os.tmpdir()` | What works | What does NOT |
|
|
172
|
+
|---|---|---|---|
|
|
173
|
+
| **WSL/Linux** | `/tmp` | `/tmp/…` | `$HOME`, project dir, arbitrary |
|
|
174
|
+
| **macOS** | `$TMPDIR` (`/var/folders/<hash>/T/`) | `$TMPDIR/…` | `/tmp` (→ `/private/tmp`), `$HOME`, project dir |
|
|
175
|
+
|
|
176
|
+
**⚠️ macOS trap:** `/tmp` is a symlink to `/private/tmp` and is NOT the
|
|
177
|
+
`os.tmpdir()` root — it is rejected even though it "looks like" the temp dir.
|
|
178
|
+
`$HOME` and the project directory are also rejected — they are not roots.
|
|
179
|
+
Only `$TMPDIR` works. Verified 2026-10-28 on macOS 15.7.
|
|
180
|
+
|
|
181
|
+
**Rule: always resolve `os.tmpdir()` first, don't hardcode `/tmp`.**
|
|
182
|
+
Inside `fabric_exec` the temp dir is a host path — read it once with `pi.bash`
|
|
183
|
+
and reuse (works on both WSL and macOS):
|
|
184
|
+
|
|
185
|
+
```ts
|
|
186
|
+
// Resolve the workspace root ONCE
|
|
187
|
+
const tmp = (await pi.bash({ cmd: "node -e 'console.log(require(\"os\").tmpdir())'" })).output.trim();
|
|
188
|
+
// WSL: /tmp
|
|
189
|
+
// macOS: /var/folders/0t/4rsp…/T/
|
|
190
|
+
|
|
191
|
+
await mcp.chrome_devtools.take_screenshot({ pageId: 1, filePath: `${tmp}/page.png` });
|
|
192
|
+
await mcp.chrome_devtools.take_screenshot({ pageId: 1, uid: "1_5", filePath: `${tmp}/el.png` });
|
|
193
|
+
await mcp.chrome_devtools.take_screenshot({ pageId: 1, fullPage: true, filePath: `${tmp}/full.png` });
|
|
194
|
+
await mcp.chrome_devtools.take_screenshot({ pageId: 1, format: "jpeg", quality: 70, filePath: `${tmp}/page.jpg` });
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
If a path is rejected with `Access denied: … not within any of the configured
|
|
198
|
+
workspace roots`, you used a hardcoded `/tmp` on macOS or a non-root path —
|
|
199
|
+
switch to the resolved `os.tmpdir()` above. Do NOT retry `$HOME` or the
|
|
200
|
+
project dir: they are not roots and will also fail.
|
|
201
|
+
|
|
202
|
+
> **To broaden roots** (trusted local client only): launch the server with
|
|
203
|
+
> `--workspace=<path>` (repeatable) or `--workspace=/` (deprecated, full FS).
|
|
204
|
+
> This is a server-side flag in `~/.mcporter/mcporter.json` `mcpServers`,
|
|
205
|
+
> not a runtime argument — edit the config and restart the server. Don't do
|
|
206
|
+
> this for shared/CI environments.
|
|
207
|
+
|
|
208
|
+
### How to view the screenshot
|
|
209
|
+
|
|
210
|
+
`pi.read` the file — but **only vision-capable models see images**. Non-vision
|
|
211
|
+
models (e.g. GLM-5.2) get `tool image omitted: model does not support images`.
|
|
212
|
+
|
|
213
|
+
> **If you can't see, ask someone who can.** Delegate to a vision-capable
|
|
214
|
+
> sub-agent (`pixso-analyst`, model Qwen3.8-27B) via `agents.ask`, or ask
|
|
215
|
+
> the user. Don't guess what a screenshot shows — either see it or have it
|
|
216
|
+
> described to you.
|
|
217
|
+
|
|
218
|
+
```ts
|
|
219
|
+
// You (vision model): pi.read directly
|
|
220
|
+
await pi.read({ path: `${tmp}/page.png` });
|
|
221
|
+
|
|
222
|
+
// You (non-vision): delegate to a seeing actor
|
|
223
|
+
await agents.ask({ id: "pixso-analyst", message: `Read ${tmp}/page.png and describe the layout` });
|
|
224
|
+
|
|
225
|
+
// For most verification, skip screenshots entirely — take_snapshot (a11y text)
|
|
226
|
+
// is sufficient and doesn't need vision.
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
### Element screenshots vs full page
|
|
230
|
+
|
|
231
|
+
`uid: "1_5"` screenshots **just that element** (clipped to its bounding box).
|
|
232
|
+
Without `uid`, you get the **current viewport**. `fullPage: true` captures the
|
|
233
|
+
entire scrollable page (incompatible with `uid`).
|
|
234
|
+
|
|
235
|
+
## Pitfalls
|
|
236
|
+
|
|
237
|
+
- **`get_network_request` truncates large response bodies** (~10KB observed of a
|
|
238
|
+
29KB body). A field missing from the captured slice is NOT evidence it is
|
|
239
|
+
absent — verify by re-fetching in page context:
|
|
240
|
+
`evaluate_script` with `() => fetch(url).then(r => r.json()).then(j => j.field)`.
|
|
241
|
+
- **HMR staleness**: after editing frontend code, hard-reload
|
|
242
|
+
(`navigate_page { type: "reload", ignoreCache: true }`) before measuring — HMR
|
|
243
|
+
propagation to the open tab is unreliable, and measurements on the stale
|
|
244
|
+
bundle give false "fix didn't work" conclusions.
|
|
245
|
+
- **DOM text probes false-negative on tooltips/popovers**: text nodes may have
|
|
246
|
+
children, so `e.children.length === 0 && textContent === X` misses them. For
|
|
247
|
+
"is text X rendered?" checks, trust the screenshot or scrollWidth metrics.
|
|
248
|
+
## When you need more
|
|
249
|
+
|
|
250
|
+
- **First-run setup** (Chrome instances / ports / config missing) → `pi.read({ path: "<skill-dir>/references/setup.md" })`
|
|
251
|
+
- **Tool schemas** → `tools.describe({ ref: "mcp.chrome_devtools.<tool>" })` — live, always current. Don't read static tool lists.
|
|
252
|
+
- **Cookbook workflows** (table scraping, lazy-load, login, SPA debug, perf trace) → `pi.read({ path: "<skill-dir>/references/recipes.md" })`
|
|
253
|
+
|
|
254
|
+
Load these only when the task needs them — that's the whole point.
|
|
255
|
+
|
|
256
|
+
## Anti-patterns
|
|
257
|
+
|
|
258
|
+
- ❌ `take_screenshot` to read text/DOM → use `take_snapshot` (cheaper, precise)
|
|
259
|
+
- ❌ Screenshot paths outside workspace roots → `Access denied`; resolve `os.tmpdir()` first (NOT hardcoded `/tmp` — fails on macOS) → see Screenshots section
|
|
260
|
+
- ❌ Multiple `fill` calls for one form → use `fill_form` (one round-trip)
|
|
261
|
+
- ❌ Guessing selectors when you have a `uid` → snapshot first, use the uid
|
|
262
|
+
- ❌ **`evaluate_script` for actions** (`.click()`, `.value=`, `scrollTo`) → use `click` / `fill` / `press_key` (real events + snapshot)
|
|
263
|
+
- ❌ Fresh `evaluate_script` for colors/box-model → see the `chrome-css` skill
|
|
264
|
+
- ❌ First-call `MCP error -32001: Request timed out` → cold start, not a crash → wait ~8s and retry
|
|
265
|
+
|
|
266
|
+
## Troubleshooting
|
|
267
|
+
|
|
268
|
+
Most failures are cold starts or stale uids, not crashes — **wait and retry**
|
|
269
|
+
first. Config changed mid-session? Force a reconnect with
|
|
270
|
+
`tools.call({ ref: "mcp.$reload" })` (closes and reopens every MCP connection).
|
|
271
|
+
|
|
272
|
+
| Symptom | Fix |
|
|
273
|
+
|---|---|
|
|
274
|
+
| `MCP error -32001: Request timed out` on first call after idle | cold start (`npx -y chrome-devtools-mcp@latest` + Chrome launch) → wait ~8s, retry; the server stays up afterwards |
|
|
275
|
+
| `appears offline` / `Connection closed` | tab/process crashed → retry `list_pages`; if persistent, see setup.md |
|
|
276
|
+
| `Element with uid … not found` | stale uid, or element missing from the a11y tree (add a `role`) → `take_snapshot` again, use the fresh uid |
|
|
277
|
+
| `Navigation timeout of 10000 ms exceeded` | slow site → retry `navigate_page` (often lands 2nd try); or raise `timeout` |
|