Chris Tate
4cc6ca40b7
Before this change, the main skill served by the CLI (`agent-browser
skills get agent-browser`) was a ~40-line discovery stub whose content
was essentially "run `agent-browser skills get <name>` before doing
anything." Agents already inside the CLI got no signal from it — the
content they needed to actually use the tool lived only in the `--full`
references.
Split the two jobs apart:
- **`skill-data/core/`** (new) — the runtime usage guide. 420-line
`SKILL.md` covering the snapshot-and-ref loop, common workflows
(login, extract, screenshot, multi-tab, sessions, iframes, dialogs),
waiting strategies, element selection strategies, troubleshooting,
and when to load a specialized skill. Supplementary `references/` and
`templates/` (moved from `skills/agent-browser/`) provide the full
command reference under `--full`.
- **`skills/agent-browser/SKILL.md`** — still the discovery stub that
`npx skills add` installs, now marked `hidden: true` so it stays out
of `skills list` inside the CLI. Body is a clean pointer to
`agent-browser skills get core` and the specialized skills.
The `hidden: true` frontmatter flag is a new, general mechanism: skills
marked hidden are omitted from `skills list` and `skills get --all` but
can still be fetched by explicit name. This keeps the stub reachable
for anyone who installed via `npx skills add` without polluting the
CLI-side skill listing.
## Behavior
```
$ agent-browser skills list
agentcore Run agent-browser on AWS Bedrock AgentCore cloud browsers...
core Core agent-browser usage guide. Read this before running...
dogfood Systematically explore and test a web application...
electron Automate Electron desktop apps (VS Code, Slack, Discord...)
slack Interact with Slack workspaces using browser automation...
vercel-sandbox Run agent-browser + Chrome inside Vercel Sandbox microVMs...
$ agent-browser skills get core # the actual usage guide
# ~420 lines of workflows, patterns, troubleshooting
$ agent-browser skills get agent-browser # still works if called explicitly
# the thin stub, now pointing at `core`
```
External `npx skills add vercel-labs/agent-browser` behavior is
unchanged: it finds and installs the thin `agent-browser` stub, which
tells the agent to run `agent-browser skills get core` for real
content. Version drift protection is preserved — the stub is the only
thing that gets copied; the real content is always runtime-fetched.
## Updated
- `cli/src/skills.rs` — `SkillInfo.hidden: bool`, parsed from
frontmatter; `run_list` and `run_get --all` filter it. 3 new unit
tests for the frontmatter parser.
- `cli/src/output.rs` — top-level `--help` and `skills` subcommand help
reference `skills get core` / `skills get core --full`.
- `AGENTS.md` — "update these files for user-facing features" now
points at `skill-data/core/` instead of the stub, with a note that
the stub is not the right place for feature content.
- `README.md`, `docs/src/app/skills/page.mdx` — describe the new
split and `skills get core --full` as the recommended entry point.
- `evals/cases/{command-usage,skill-selection}.ts` — expect
`skills get core` in agent output instead of `skills get
agent-browser`. Eval lib still reads `skills/agent-browser/SKILL.md`
(simulating what an agent sees after `npx skills add`).
All 11 skills unit tests pass. `cargo clippy -- -D warnings` and
`cargo fmt --check` clean. Verified end-to-end: `skills list` shows
`core` + specialized (no stub), `skills get core` returns the new
content, `skills get agent-browser` still returns the stub on explicit
request.
121 lines
3.3 KiB
Markdown
121 lines
3.3 KiB
Markdown
# Profiling
|
|
|
|
Capture Chrome DevTools performance profiles during browser automation for performance analysis.
|
|
|
|
**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
|
|
|
|
## Contents
|
|
|
|
- [Basic Profiling](#basic-profiling)
|
|
- [Profiler Commands](#profiler-commands)
|
|
- [Categories](#categories)
|
|
- [Use Cases](#use-cases)
|
|
- [Output Format](#output-format)
|
|
- [Viewing Profiles](#viewing-profiles)
|
|
- [Limitations](#limitations)
|
|
|
|
## Basic Profiling
|
|
|
|
```bash
|
|
# Start profiling
|
|
agent-browser profiler start
|
|
|
|
# Perform actions
|
|
agent-browser navigate https://example.com
|
|
agent-browser click "#button"
|
|
agent-browser wait 1000
|
|
|
|
# Stop and save
|
|
agent-browser profiler stop ./trace.json
|
|
```
|
|
|
|
## Profiler Commands
|
|
|
|
```bash
|
|
# Start profiling with default categories
|
|
agent-browser profiler start
|
|
|
|
# Start with custom trace categories
|
|
agent-browser profiler start --categories "devtools.timeline,v8.execute,blink.user_timing"
|
|
|
|
# Stop profiling and save to file
|
|
agent-browser profiler stop ./trace.json
|
|
```
|
|
|
|
## Categories
|
|
|
|
The `--categories` flag accepts a comma-separated list of Chrome trace categories. Default categories include:
|
|
|
|
- `devtools.timeline` -- standard DevTools performance traces
|
|
- `v8.execute` -- time spent running JavaScript
|
|
- `blink` -- renderer events
|
|
- `blink.user_timing` -- `performance.mark()` / `performance.measure()` calls
|
|
- `latencyInfo` -- input-to-latency tracking
|
|
- `renderer.scheduler` -- task scheduling and execution
|
|
- `toplevel` -- broad-spectrum basic events
|
|
|
|
Several `disabled-by-default-*` categories are also included for detailed timeline, call stack, and V8 CPU profiling data.
|
|
|
|
## Use Cases
|
|
|
|
### Diagnosing Slow Page Loads
|
|
|
|
```bash
|
|
agent-browser profiler start
|
|
agent-browser navigate https://app.example.com
|
|
agent-browser wait --load networkidle
|
|
agent-browser profiler stop ./page-load-profile.json
|
|
```
|
|
|
|
### Profiling User Interactions
|
|
|
|
```bash
|
|
agent-browser navigate https://app.example.com
|
|
agent-browser profiler start
|
|
agent-browser click "#submit"
|
|
agent-browser wait 2000
|
|
agent-browser profiler stop ./interaction-profile.json
|
|
```
|
|
|
|
### CI Performance Regression Checks
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
agent-browser profiler start
|
|
agent-browser navigate https://app.example.com
|
|
agent-browser wait --load networkidle
|
|
agent-browser profiler stop "./profiles/build-${BUILD_ID}.json"
|
|
```
|
|
|
|
## Output Format
|
|
|
|
The output is a JSON file in Chrome Trace Event format:
|
|
|
|
```json
|
|
{
|
|
"traceEvents": [
|
|
{ "cat": "devtools.timeline", "name": "RunTask", "ph": "X", "ts": 12345, "dur": 100, ... },
|
|
...
|
|
],
|
|
"metadata": {
|
|
"clock-domain": "LINUX_CLOCK_MONOTONIC"
|
|
}
|
|
}
|
|
```
|
|
|
|
The `metadata.clock-domain` field is set based on the host platform (Linux or macOS). On Windows it is omitted.
|
|
|
|
## Viewing Profiles
|
|
|
|
Load the output JSON file in any of these tools:
|
|
|
|
- **Chrome DevTools**: Performance panel > Load profile (Ctrl+Shift+I > Performance)
|
|
- **Perfetto UI**: https://ui.perfetto.dev/ -- drag and drop the JSON file
|
|
- **Trace Viewer**: `chrome://tracing` in any Chromium browser
|
|
|
|
## Limitations
|
|
|
|
- Only works with Chromium-based browsers (Chrome, Edge). Not supported on Firefox or WebKit.
|
|
- Trace data accumulates in memory while profiling is active (capped at 5 million events). Stop profiling promptly after the area of interest.
|
|
- Data collection on stop has a 30-second timeout. If the browser is unresponsive, the stop command may fail.
|