Forked from yagil/chrome-cdp-control
Forked from yagil/chrome-cdp-control
SKILL.md
---
name: chrome-cdp-control
display-name: Chrome CDP Control
description: Connect to and operate a user-visible Chrome session through CDP
for browser inspection, navigation, and interaction.
---
# Chrome CDP Control
Use Chrome DevTools Protocol (CDP) when the user asks you to inspect or operate their Chrome browser. Take initiative: inspect the live page, perform requested browser actions, verify the result, and report concise outcomes.
## Operating principles
- Treat the browser as user-controlled state. Never close, replace, or relaunch an existing browser without explaining the impact and obtaining approval when data could be lost.
- Prefer a separately launched CDP profile. Modern Chrome may ignore remote-debugging flags for its default profile.
- Never read, print, screenshot, or retain passwords, verification codes, real card numbers, real security codes, session tokens, cookie values, or other secrets. Leave real secret-entry steps to the user.
- Exception: when the user explicitly requests testing in a clearly identified payment-provider test mode, provider-published test card values are non-secret test data. You may enter, inspect, and screenshot those values. Never use this exception for live mode or user-provided payment details.
- Inspect before acting. Verify resulting URLs, visible notices, or data rows after changes. In a known batch, run these checks locally with `wait-for` and return only the needed proof; a full page dump after every action is unnecessary.
- Prepare consequential changes, summarize them, and pause before the final irreversible or high-impact action unless the user has explicitly authorized that exact action.
- Use exact URLs, selectors, accessible names, and visible text. Do not guess when multiple targets match.
- Prefer normal mouse and keyboard CDP events over calling `element.click()` or assigning `input.value`; framework-controlled pages often ignore synthetic DOM changes.
## Connect or launch
1. Test the standard endpoint:
```bash
curl -fsS http://127.0.0.1:9222/json/version
```
2. If unavailable, inspect running browser processes and listening ports. A Chrome process without a remote-debugging endpoint cannot be attached in place.
3. If the user wants you to launch a controllable instance, call `get_scratchpad_folder`, create a profile folder there, and launch:
```bash
open -na "Google Chrome" --args \
--remote-debugging-address=127.0.0.1 \
--remote-debugging-port=9222 \
--user-data-dir="<scratchpad>/chrome-cdp-profile" \
"<requested-url>"
```
4. Explain that a scratchpad profile persists across immediate restarts only while that scratchpad exists. For durable use, offer a dedicated persistent profile and obtain permission before writing outside the workspace.
5. Never expose the CDP port beyond loopback.
## Use the bundled helper
Resolve `scripts/cdp.mjs` relative to this `SKILL.md`. It requires Node 22 or newer with built-in WebSocket and has no third-party dependencies.
```bash
node <skill-folder>/scripts/cdp.mjs list
node <skill-folder>/scripts/cdp.mjs read --target-id '<id-from-list>' --selector '#status' --limit 1000
node <skill-folder>/scripts/cdp.mjs run --target-id '<id-from-list>' --file '<scratchpad>/workflow.json'
node <skill-folder>/scripts/cdp.mjs body --target-url 'example.com/path' --limit 4000
node <skill-folder>/scripts/cdp.mjs navigate --target-url 'example.com' --url 'https://example.com/new'
node <skill-folder>/scripts/cdp.mjs new --url 'https://example.com/'
node <skill-folder>/scripts/cdp.mjs click-text --target-url 'example.com' --text 'Continue'
node <skill-folder>/scripts/cdp.mjs type --target-url 'example.com' --selector 'input[name=email]' --text 'person@example.com'
node <skill-folder>/scripts/cdp.mjs eval --target-url 'example.com' --expression 'document.title'
node <skill-folder>/scripts/cdp.mjs screenshot --target-url 'example.com' --output '/absolute/scratchpad/page.png'
node <skill-folder>/scripts/cdp.mjs clear-cookies --domains 'example.com,login.example.com'
```
`--target-id` selects an exact page ID from `list`. All per-page commands also accept `--target-url`, a case-sensitive URL substring that must match exactly one page. Supply one selector, not both. Endpoint discovery has a 10-second timeout; commands have a 30-second connection deadline (`run --timeout-ms` overrides it). Individual page evaluations are capped at 5 seconds.
## Interaction workflow
1. Run `list` and identify the exact page target. Reuse its ID while working on that tab.
2. Inspect relevant content with `read --selector CSS`. If the page structure is unknown, use a bounded `body` once, then focused `eval` for labels, roles, and selectors without reading secret-field values.
3. For repeated, already-understood actions, read [references/workflows.md](references/workflows.md) and use `run` with a JSON sequence of `fill`, `click`, `wait-for`, `read`, and `checkpoint` steps. It uses one connection and emits one compact receipt. Verify application state with waits and a small final read. Checkpoints only label progress; they do not verify success.
4. Use individual commands for exploration and navigation. Batch only actions already covered by the user's authorization. Stop at unknown page state, authentication, secret entry, or a required approval; inspect before continuing.
5. After a failed batch, inspect `completedSteps`, `failedStep`, and live state. Earlier writes may have succeeded. Never automatically replay the whole file; reconcile and construct only the remaining work. `outcomeUnknown` flags an interrupted input dispatch, not a guarantee that other failures had no effects.
6. For controls outside the workflow's ordinary text inputs and buttons, inspect their state and use focused CDP mouse/key events. Keep the user informed at meaningful checkpoints.
## Tabs and screenshots
- Create a new tab with `new` when testing a path should not disrupt the user's current page.
- Screenshots must be written to the scratchpad, not the workspace. Inspect them with `view_images` if needed.
- Before taking a screenshot, ensure no password, verification code, real payment credential, private key, or token is visible. Provider-published test values are allowed only under the explicit test-mode exception above.
## Cookies and site data
- `clear-cookies --domains` deletes only matching-domain cookies and never prints cookie names or values.
- Domain matching includes subdomains of each requested domain.
- Cookie deletion does not clear local storage, IndexedDB, caches, or service workers.
- To clear all storage for an origin, use CDP `Storage.clearDataForOrigin` only after explaining that it can reset an unfinished flow. Keep unrelated origins untouched.
- Clearing local browser data does not remove server-side sessions, fraud flags, account state, or remote data.
## Troubleshooting
- If a click does nothing, inspect whether the text belongs to a wrapper or shadow/custom element. Use the smallest visible interactive element and real mouse events.
- If typed text appears but the app does not react, focus the field and use `Input.insertText`; follow with appropriate key events or blur.
- If a SPA is still loading, wait and inspect again rather than repeating a submission.
- If `/json/list` shows a changed target ID after authentication, rediscover the target instead of reusing an old WebSocket URL.
- If authentication redirects unexpectedly, inspect the active account indicator and URL before continuing.
SKILL.md
---
name: chrome-cdp-control
display-name: Chrome CDP Control
description: Connect to and operate a user-visible Chrome session through CDP
for browser inspection, navigation, and interaction.
---
# Chrome CDP Control
Use Chrome DevTools Protocol (CDP) when the user asks you to inspect or operate their Chrome browser. Take initiative: inspect the live page, perform requested browser actions, verify the result, and report concise outcomes.
## Operating principles
- Treat the browser as user-controlled state. Never close, replace, or relaunch an existing browser without explaining the impact and obtaining approval when data could be lost.
- Prefer a separately launched CDP profile. Modern Chrome may ignore remote-debugging flags for its default profile.
- Never read, print, screenshot, or retain passwords, verification codes, real card numbers, real security codes, session tokens, cookie values, or other secrets. Leave real secret-entry steps to the user.
- Exception: when the user explicitly requests testing in a clearly identified payment-provider test mode, provider-published test card values are non-secret test data. You may enter, inspect, and screenshot those values. Never use this exception for live mode or user-provided payment details.
- Inspect before acting. Verify resulting URLs, visible notices, or data rows after changes. In a known batch, run these checks locally with `wait-for` and return only the needed proof; a full page dump after every action is unnecessary.
- Prepare consequential changes, summarize them, and pause before the final irreversible or high-impact action unless the user has explicitly authorized that exact action.
- Use exact URLs, selectors, accessible names, and visible text. Do not guess when multiple targets match.
- Prefer normal mouse and keyboard CDP events over calling `element.click()` or assigning `input.value`; framework-controlled pages often ignore synthetic DOM changes.
## Connect or launch
1. Test the standard endpoint:
```bash
curl -fsS http://127.0.0.1:9222/json/version
```
2. If unavailable, inspect running browser processes and listening ports. A Chrome process without a remote-debugging endpoint cannot be attached in place.
3. If the user wants you to launch a controllable instance, call `get_scratchpad_folder`, create a profile folder there, and launch:
```bash
open -na "Google Chrome" --args \
--remote-debugging-address=127.0.0.1 \
--remote-debugging-port=9222 \
--user-data-dir="<scratchpad>/chrome-cdp-profile" \
"<requested-url>"
```
4. Explain that a scratchpad profile persists across immediate restarts only while that scratchpad exists. For durable use, offer a dedicated persistent profile and obtain permission before writing outside the workspace.
5. Never expose the CDP port beyond loopback.
## Use the bundled helper
Resolve `scripts/cdp.mjs` relative to this `SKILL.md`. It requires Node 22 or newer with built-in WebSocket and has no third-party dependencies.
```bash
node <skill-folder>/scripts/cdp.mjs list
node <skill-folder>/scripts/cdp.mjs read --target-id '<id-from-list>' --selector '#status' --limit 1000
node <skill-folder>/scripts/cdp.mjs run --target-id '<id-from-list>' --file '<scratchpad>/workflow.json'
node <skill-folder>/scripts/cdp.mjs body --target-url 'example.com/path' --limit 4000
node <skill-folder>/scripts/cdp.mjs navigate --target-url 'example.com' --url 'https://example.com/new'
node <skill-folder>/scripts/cdp.mjs new --url 'https://example.com/'
node <skill-folder>/scripts/cdp.mjs click-text --target-url 'example.com' --text 'Continue'
node <skill-folder>/scripts/cdp.mjs type --target-url 'example.com' --selector 'input[name=email]' --text 'person@example.com'
node <skill-folder>/scripts/cdp.mjs eval --target-url 'example.com' --expression 'document.title'
node <skill-folder>/scripts/cdp.mjs screenshot --target-url 'example.com' --output '/absolute/scratchpad/page.png'
node <skill-folder>/scripts/cdp.mjs clear-cookies --domains 'example.com,login.example.com'
```
`--target-id` selects an exact page ID from `list`. All per-page commands also accept `--target-url`, a case-sensitive URL substring that must match exactly one page. Supply one selector, not both. Endpoint discovery has a 10-second timeout; commands have a 30-second connection deadline (`run --timeout-ms` overrides it). Individual page evaluations are capped at 5 seconds.
## Interaction workflow
1. Run `list` and identify the exact page target. Reuse its ID while working on that tab.
2. Inspect relevant content with `read --selector CSS`. If the page structure is unknown, use a bounded `body` once, then focused `eval` for labels, roles, and selectors without reading secret-field values.
3. For repeated, already-understood actions, read [references/workflows.md](references/workflows.md) and use `run` with a JSON sequence of `fill`, `click`, `wait-for`, `read`, and `checkpoint` steps. It uses one connection and emits one compact receipt. Verify application state with waits and a small final read. Checkpoints only label progress; they do not verify success.
4. Use individual commands for exploration and navigation. Batch only actions already covered by the user's authorization. Stop at unknown page state, authentication, secret entry, or a required approval; inspect before continuing.
5. After a failed batch, inspect `completedSteps`, `failedStep`, and live state. Earlier writes may have succeeded. Never automatically replay the whole file; reconcile and construct only the remaining work. `outcomeUnknown` flags an interrupted input dispatch, not a guarantee that other failures had no effects.
6. For controls outside the workflow's ordinary text inputs and buttons, inspect their state and use focused CDP mouse/key events. Keep the user informed at meaningful checkpoints.
## Tabs and screenshots
- Create a new tab with `new` when testing a path should not disrupt the user's current page.
- Screenshots must be written to the scratchpad, not the workspace. Inspect them with `view_images` if needed.
- Before taking a screenshot, ensure no password, verification code, real payment credential, private key, or token is visible. Provider-published test values are allowed only under the explicit test-mode exception above.
## Cookies and site data
- `clear-cookies --domains` deletes only matching-domain cookies and never prints cookie names or values.
- Domain matching includes subdomains of each requested domain.
- Cookie deletion does not clear local storage, IndexedDB, caches, or service workers.
- To clear all storage for an origin, use CDP `Storage.clearDataForOrigin` only after explaining that it can reset an unfinished flow. Keep unrelated origins untouched.
- Clearing local browser data does not remove server-side sessions, fraud flags, account state, or remote data.
## Troubleshooting
- If a click does nothing, inspect whether the text belongs to a wrapper or shadow/custom element. Use the smallest visible interactive element and real mouse events.
- If typed text appears but the app does not react, focus the field and use `Input.insertText`; follow with appropriate key events or blur.
- If a SPA is still loading, wait and inspect again rather than repeating a submission.
- If `/json/list` shows a changed target ID after authentication, rediscover the target instead of reusing an old WebSocket URL.
- If authentication redirects unexpectedly, inspect the active account indicator and URL before continuing.