Claude Skill

chromium-browser

Imported from paulrberg/agent-skills/skills/chromium-browser.

LLM Mart · 0 points · 0 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download paulrberg-agent-skills-skills_chromium-browser-913232a.zip · 6 KB

paulrberg/agent-skills 94 7 forks MIT Updated 5h ago

Part of paulrberg/agent-skills — 42 skills

Install

skills CLI npx skills add https://github.com/PaulRBerg/agent-skills/tree/main/skills/chromium-browser

Claude Code

claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install paulrberg-agent-skills@llmmart

Git git clone https://github.com/PaulRBerg/agent-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole paulrberg/agent-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Chromium Browser

Operate the configured Chrome DevTools MCP against the existing shared browser without disrupting unrelated tabs or authenticated state.

This skill owns rendered browser UI interaction, inspection, automation, and verification through shared Chromium. Use search, fetch, APIs, CLIs, or connectors for retrieval when they fit, and host native-app tools for non-browser UI. Do not use native-app tools as a fallback around this skill's shared-browser attachment, page-ownership, or privacy rules. If the user selects another available browser integration, follow its tool contract without mixing controllers.

Environment Contract

Treat ~/.local/libexec/mcp/chrome-devtools and the tools exposed in the current session as authoritative. The wrapper owns server versioning, flags, logging, and browser attachment; do not run the MCP package directly.
The MCP attaches to an existing remote-debugging browser. Never launch a fallback browser or create another profile when attachment fails.
Treat the browser as shared, authenticated, and concurrently used by the user and other agents. Inspect only pages relevant to the task and do not surface unrelated tab titles or content.
Trust the live tool inventory; an absent tool is unavailable in this session. Do not advise editing client MCP configuration as a troubleshooting shortcut.

Reference Routing

For Wayback Machine capture discovery or replay research, read references/wayback-machine.md before making any Wayback request. Otherwise do not load it. Discover captures through serialized APIs outside Chromium, then open only the selected replay when rendered inspection adds evidence.

Page Ownership

Call list_pages before interacting and preserve the initial pages as pre-existing state.
Prefer new_page with background: true when a fresh page satisfies the task. Record the exact pageId returned by every page this task creates; never infer ownership from a later page-list difference.
Pass an explicit pageId to every page-scoped tool. Do not rely on selected-page state; use select_page only when deliberately bringing a page to the foreground or recovering the closed-page context described below.
Navigate or mutate a pre-existing page only when the task explicitly depends on that page's current state. Never close a pre-existing page.
Before closing an owned page that is currently selected, select_page a previously observed surviving page (for example the page selected before this task opened its own) with bringToFront: false, then close_page the owned page by its ID. If the close still returns the closed-page error described in Troubleshooting, treat it as a likely success and confirm once using that recovery rather than retrying the close.
At completion, close only the recorded pages created by this task unless the user asked to leave one open.

Interaction and Evidence

On one page, navigate, wait for a useful known signal, take a fresh snapshot, then interact with identifiers from that snapshot. Refresh it after navigation or meaningful DOM changes.
Prefer take_snapshot for structure and automation, take_screenshot for visual evidence, and evaluate_script for information absent from the accessibility tree. Accept wrapper screenshot defaults unless the task requires lossless or full-resolution output.
Keep action responses small with includeSnapshot: false unless the updated state is immediately needed. Paginate and filter console, network, memory, and other high-volume results.
When a cookie consent popup appears, select only necessary or essential cookies by default, including through its settings when needed. If no such option is available, accept all cookies and continue.
Use filePath for large screenshots, snapshots, traces, recordings, or response bodies, writing only to a task-authorized path inside the server's workspace roots, such as a git-ignored .ai/ directory; the server rejects paths outside them, including agent scratchpads. Unrestricted path capability is not write authorization.
Parallelize independent pages when useful, but preserve causal order for calls targeting the same page.

Authority and Privacy

Read-only inspection of task-relevant authenticated state is allowed when the task calls for it. Submitting forms, changing accounts, installing extensions, making purchases, or causing another external mutation requires the same authority that action would require outside the browser.
Network-header redaction is an intentional server boundary. Do not bypass it or seek credentials through page or process introspection.

Troubleshooting

If closing an owned page returns The selected page has been closed and list_pages repeats it, the close may have succeeded while MCP retained a stale selection. Select a previously observed surviving page with bringToFront: false, then call list_pages and confirm the owned page ID is absent. This recovery attempts only to repair MCP context: do not navigate, inspect, or close the surviving page, and suppress unrelated titles and content from results. Do not repeat the close or create another tab to recover selection.
If select_page also returns the same closed-page error, stop MCP recovery attempts and report the stale session context. A read-only /json/list request at the configured debugging endpoint can confirm that a task page's known, unique, unchanged URL is absent; filter locally and return only that result, never unrelated targets. This is closure evidence, not MCP recovery or authorization to control the browser through another route. MCP pageId values are not CDP target IDs. If the owned page cannot be identified reliably, report cleanup as unverified; do not infer ownership from the endpoint list or use it to close tabs.
On attachment or transport failure, distinguish the browser endpoint from the MCP process: check the debugging endpoint at http://127.0.0.1:${PRB_AGENT_CHROMIUM_PORT:-9222}/json/version, then inspect the newest per-process log under $XDG_CACHE_HOME/chrome-devtools-mcp/logs/ or, when unset, ~/.cache/chrome-devtools-mcp/logs/.
A responsive endpoint proves the browser process is alive, not that renderers can start. If new_page times out and tabs show a crashed icon or Untitled, stop repeated creation attempts and check browser health separately from MCP transport health. A failed creation can leave a tab without returning a pageId; do not infer ownership from a later page list or close unidentified tabs.
After a macOS Homebrew Chromium upgrade, compare the endpoint's Browser version with plutil -extract CFBundleShortVersionString raw /Applications/Chromium.app/Contents/Info.plist. Confirm the running process uses that app bundle and inspect its start time and versioned framework/helper paths. Homebrew can replace the bundle while the old process keeps running, removing helpers it needs for new renderers; existing pages and /json/version can still work. A version mismatch alone is a clue, not proof of the failure.
Report the failed layer and evidence. Do not change client configuration or wrapper flags without authorization for that configuration work. Do not automatically restart the shared browser during ordinary browsing or from the wrapper. An explicit request to repair the browser authorizes a graceful restart using the same profile and debugging port. Record those arguments first and preserve the session; chrome://restart requests a session-restoring restart. If the old process exits but cannot relaunch after an upgrade, confirm it has exited, then reopen the installed executable with the recorded profile/port arguments and --restore-last-session, never a fallback profile. Respect any unsaved-work prompt. Recheck the live version, call list_pages for fresh IDs, verify pre-existing pages were restored, and test creation and navigation on an owned page before closing it.
When a requested capability is missing, confirm the current tool inventory and wrapper configuration, then report the boundary. Do not invent a fallback that weakens the configured privacy or concurrency defaults.

Completion requires fresh tool evidence for the requested outcome and confirmation that task-created pages were either closed or intentionally left open.

Files (agent-skills)

agents

openai.yaml 42 B

policy:
  allow_implicit_invocation: true

references

wayback-machine.md 6.5 KB

# Wayback Machine

Use the Wayback APIs to select one capture, then use shared Chromium only when inspecting the rendered replay adds
evidence. The traffic limits below are local safety invariants derived from observed throttling, not Internet Archive
service guarantees.

## Traffic Safety

- Run API discovery outside Chromium with one foreground request at a time. Wait for it to finish before starting the
  next request.
- Never parallelize, poll, or launch background Wayback probes. Do not configure retries.
- Bound every prefix, host, or domain query with selective filters, collapse rules, and a positive `limit`.
- On the first HTTP `429` or connection timeout from `archive.org` or `web.archive.org`, stop all Wayback traffic for
  the rest of the task and session. Do not retry through CDX, Availability, replay navigation, Chromium, a proxy, or
  another route. Report that the archive evidence source is blocked and leave unsupported conclusions unknown.

## CDX Discovery

Query `https://web.archive.org/cdx/search/cdx` with these parameters. The
[official CDX documentation](https://github.com/internetarchive/wayback/blob/master/wayback-cdx-server/README.md) is
authoritative.

| Parameter   | Use                                                                                                                                |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `url`       | Required capture target. URL-encode its value, especially when the target contains its own query string.                           |
| `matchType` | `exact` (default), `prefix` for a path tree, `host` for one host, or `domain` for the host and all subdomains.                     |
| `from`      | Inclusive lower timestamp bound with 1–14 digits in `yyyyMMddhhmmss` order.                                                        |
| `to`        | Inclusive upper timestamp bound with 1–14 digits in `yyyyMMddhhmmss` order.                                                        |
| `filter`    | Repeatable `[!]field:regex` predicate, such as `statuscode:200`; repeated filters compose constraints.                             |
| `collapse`  | Keep the first of adjacent rows equal on `field`, or on the first `N` characters with `field:N`; repeat for additional reductions. |
| `limit`     | Maximum returned rows. Use a positive value; negative limits may require scanning the search space.                                |
| `output`    | Use `json` for a JSON array whose first row contains the field names and whose remaining rows are captures.                        |

Collapse is adjacency-based, not global deduplication: a duplicate outside the neighboring run remains. For example,
`collapse=timestamp:10` keeps at most the first adjacent capture per hour, while `collapse=digest` removes only adjacent
captures with the same digest.

`url=example.com/*` is an implicit path-prefix query equivalent to `url=example.com/&matchType=prefix`; it does not
enumerate the whole domain. Use explicit `matchType=domain` for the host plus its subdomains.

Run each example separately and synchronously. None retries.

### Exact URL

```sh
curl --get --fail-with-body --show-error --silent \
  --connect-timeout 10 --max-time 30 \
  'https://web.archive.org/cdx/search/cdx' \
  --data-urlencode 'url=https://example.com/path?item=1' \
  --data-urlencode 'matchType=exact' \
  --data-urlencode 'output=json' \
  --data-urlencode 'limit=50'
```

### Path Prefix

```sh
curl --get --fail-with-body --show-error --silent \
  --connect-timeout 10 --max-time 30 \
  'https://web.archive.org/cdx/search/cdx' \
  --data-urlencode 'url=https://example.com/docs/' \
  --data-urlencode 'matchType=prefix' \
  --data-urlencode 'filter=statuscode:200' \
  --data-urlencode 'collapse=urlkey' \
  --data-urlencode 'output=json' \
  --data-urlencode 'limit=100'
```

### Full Domain

```sh
curl --get --fail-with-body --show-error --silent \
  --connect-timeout 10 --max-time 30 \
  'https://web.archive.org/cdx/search/cdx' \
  --data-urlencode 'url=example.com' \
  --data-urlencode 'matchType=domain' \
  --data-urlencode 'filter=statuscode:200' \
  --data-urlencode 'collapse=urlkey' \
  --data-urlencode 'output=json' \
  --data-urlencode 'limit=100'
```

### Bounded Successful Captures

```sh
curl --get --fail-with-body --show-error --silent \
  --connect-timeout 10 --max-time 30 \
  'https://web.archive.org/cdx/search/cdx' \
  --data-urlencode 'url=https://example.com/docs/' \
  --data-urlencode 'matchType=prefix' \
  --data-urlencode 'from=20200101' \
  --data-urlencode 'to=20201231235959' \
  --data-urlencode 'filter=statuscode:200' \
  --data-urlencode 'collapse=digest' \
  --data-urlencode 'output=json' \
  --data-urlencode 'limit=100'
```

## Closest Snapshot

The [official Availability API documentation](https://archive.org/help/wayback_api.php) defines required `url` and
optional `timestamp` parameters. The timestamp accepts 1–14 digits in `YYYYMMDDhhmmss` order. When omitted, the API
returns the most recent accessible capture; when present, `archived_snapshots.closest` describes the closest accessible
capture, not necessarily an exact timestamp match.

```sh
curl --get --fail-with-body --show-error --silent \
  --connect-timeout 10 --max-time 30 \
  'https://archive.org/wayback/available' \
  --data-urlencode 'url=https://example.com/path' \
  --data-urlencode 'timestamp=20200101'
```

A successful match includes its replay URL, timestamp, status, and availability:

```json
{
  "archived_snapshots": {
    "closest": {
      "available": true,
      "url": "https://web.archive.org/web/20200102030405/https://example.com/path",
      "timestamp": "20200102030405",
      "status": "200"
    }
  }
}
```

A valid negative has this empty snapshot shape; it is not a transport failure:

```json
{ "archived_snapshots": {} }
```

## Replay Inspection

Choose one replay from a CDX row or `archived_snapshots.closest`. For a CDX row, the replay URL has the form
`https://web.archive.org/web/<timestamp>/<original>`. Open only that selected URL in the shared Chromium browser, and
only when rendered DOM, layout, script behavior, or visual state materially strengthens the evidence. Do not use
Chromium for capture discovery, calendar browsing, Availability checks, or repeated replay probes.

Follow the parent skill's page-ownership rules: record the page returned by `new_page`, pass its `pageId` explicitly,
and close only that task-created page. A replay timeout triggers the same session-long traffic stop as an API timeout.

SKILL.md 8.7 KB

---
compatibility:
  Requires PRB's attach-only Chrome DevTools MCP wrapper at ~/.local/libexec/mcp/chrome-devtools and an existing
  remote-debugging Chromium browser.
name: chromium-browser
description:
  Use Chrome DevTools through PRB's shared attach-only Chromium browser for browsing, debugging, automation, visual
  inspection, console or network analysis, performance or memory profiling, screencasts, and Wayback Machine research.
---

# Chromium Browser

Operate the configured Chrome DevTools MCP against the existing shared browser without disrupting unrelated tabs or
authenticated state.

This skill owns rendered browser UI interaction, inspection, automation, and verification through shared Chromium. Use
search, fetch, APIs, CLIs, or connectors for retrieval when they fit, and host native-app tools for non-browser UI. Do
not use native-app tools as a fallback around this skill's shared-browser attachment, page-ownership, or privacy rules.
If the user selects another available browser integration, follow its tool contract without mixing controllers.

## Environment Contract

- Treat `~/.local/libexec/mcp/chrome-devtools` and the tools exposed in the current session as authoritative. The
  wrapper owns server versioning, flags, logging, and browser attachment; do not run the MCP package directly.
- The MCP attaches to an existing remote-debugging browser. Never launch a fallback browser or create another profile
  when attachment fails.
- Treat the browser as shared, authenticated, and concurrently used by the user and other agents. Inspect only pages
  relevant to the task and do not surface unrelated tab titles or content.
- Trust the live tool inventory; an absent tool is unavailable in this session. Do not advise editing client MCP
  configuration as a troubleshooting shortcut.

## Reference Routing

For Wayback Machine capture discovery or replay research, read `references/wayback-machine.md` before making any Wayback
request. Otherwise do not load it. Discover captures through serialized APIs outside Chromium, then open only the
selected replay when rendered inspection adds evidence.

## Page Ownership

1. Call `list_pages` before interacting and preserve the initial pages as pre-existing state.
2. Prefer `new_page` with `background: true` when a fresh page satisfies the task. Record the exact `pageId` returned by
   every page this task creates; never infer ownership from a later page-list difference.
3. Pass an explicit `pageId` to every page-scoped tool. Do not rely on selected-page state; use `select_page` only when
   deliberately bringing a page to the foreground or recovering the closed-page context described below.
4. Navigate or mutate a pre-existing page only when the task explicitly depends on that page's current state. Never
   close a pre-existing page.
5. Before closing an owned page that is currently selected, `select_page` a previously observed surviving page (for
   example the page selected before this task opened its own) with `bringToFront: false`, then `close_page` the owned
   page by its ID. If the close still returns the closed-page error described in Troubleshooting, treat it as a likely
   success and confirm once using that recovery rather than retrying the close.
6. At completion, close only the recorded pages created by this task unless the user asked to leave one open.

## Interaction and Evidence

- On one page, navigate, wait for a useful known signal, take a fresh snapshot, then interact with identifiers from that
  snapshot. Refresh it after navigation or meaningful DOM changes.
- Prefer `take_snapshot` for structure and automation, `take_screenshot` for visual evidence, and `evaluate_script` for
  information absent from the accessibility tree. Accept wrapper screenshot defaults unless the task requires lossless
  or full-resolution output.
- Keep action responses small with `includeSnapshot: false` unless the updated state is immediately needed. Paginate and
  filter console, network, memory, and other high-volume results.
- When a cookie consent popup appears, select only necessary or essential cookies by default, including through its
  settings when needed. If no such option is available, accept all cookies and continue.
- Use `filePath` for large screenshots, snapshots, traces, recordings, or response bodies, writing only to a
  task-authorized path inside the server's workspace roots, such as a git-ignored `.ai/` directory; the server rejects
  paths outside them, including agent scratchpads. Unrestricted path capability is not write authorization.
- Parallelize independent pages when useful, but preserve causal order for calls targeting the same page.

## Authority and Privacy

- Read-only inspection of task-relevant authenticated state is allowed when the task calls for it. Submitting forms,
  changing accounts, installing extensions, making purchases, or causing another external mutation requires the same
  authority that action would require outside the browser.
- Network-header redaction is an intentional server boundary. Do not bypass it or seek credentials through page or
  process introspection.

## Troubleshooting

- If closing an owned page returns `The selected page has been closed` and `list_pages` repeats it, the close may have
  succeeded while MCP retained a stale selection. Select a previously observed surviving page with
  `bringToFront: false`, then call `list_pages` and confirm the owned page ID is absent. This recovery attempts only to
  repair MCP context: do not navigate, inspect, or close the surviving page, and suppress unrelated titles and content
  from results. Do not repeat the close or create another tab to recover selection.
- If `select_page` also returns the same closed-page error, stop MCP recovery attempts and report the stale session
  context. A read-only `/json/list` request at the configured debugging endpoint can confirm that a task page's known,
  unique, unchanged URL is absent; filter locally and return only that result, never unrelated targets. This is closure
  evidence, not MCP recovery or authorization to control the browser through another route. MCP `pageId` values are not
  CDP target IDs. If the owned page cannot be identified reliably, report cleanup as unverified; do not infer ownership
  from the endpoint list or use it to close tabs.
- On attachment or transport failure, distinguish the browser endpoint from the MCP process: check the debugging
  endpoint at `http://127.0.0.1:${PRB_AGENT_CHROMIUM_PORT:-9222}/json/version`, then inspect the newest per-process log
  under `$XDG_CACHE_HOME/chrome-devtools-mcp/logs/` or, when unset, `~/.cache/chrome-devtools-mcp/logs/`.
- A responsive endpoint proves the browser process is alive, not that renderers can start. If `new_page` times out and
  tabs show a crashed icon or `Untitled`, stop repeated creation attempts and check browser health separately from MCP
  transport health. A failed creation can leave a tab without returning a `pageId`; do not infer ownership from a later
  page list or close unidentified tabs.
- After a macOS Homebrew Chromium upgrade, compare the endpoint's `Browser` version with
  `plutil -extract CFBundleShortVersionString raw /Applications/Chromium.app/Contents/Info.plist`. Confirm the running
  process uses that app bundle and inspect its start time and versioned framework/helper paths. Homebrew can replace the
  bundle while the old process keeps running, removing helpers it needs for new renderers; existing pages and
  `/json/version` can still work. A version mismatch alone is a clue, not proof of the failure.
- Report the failed layer and evidence. Do not change client configuration or wrapper flags without authorization for
  that configuration work. Do not automatically restart the shared browser during ordinary browsing or from the wrapper.
  An explicit request to repair the browser authorizes a graceful restart using the same profile and debugging port.
  Record those arguments first and preserve the session; `chrome://restart` requests a session-restoring restart. If the
  old process exits but cannot relaunch after an upgrade, confirm it has exited, then reopen the installed executable
  with the recorded profile/port arguments and `--restore-last-session`, never a fallback profile. Respect any
  unsaved-work prompt. Recheck the live version, call `list_pages` for fresh IDs, verify pre-existing pages were
  restored, and test creation and navigation on an owned page before closing it.
- When a requested capability is missing, confirm the current tool inventory and wrapper configuration, then report the
  boundary. Do not invent a fallback that weakens the configured privacy or concurrency defaults.

Completion requires fresh tool evidence for the requested outcome and confirmation that task-created pages were either
closed or intentionally left open.