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.
209 lines
8.5 KiB
Markdown
209 lines
8.5 KiB
Markdown
# AGENTS.md
|
|
|
|
Instructions for AI coding agents working with this codebase.
|
|
|
|
## Package Manager
|
|
|
|
This project uses **pnpm**. Always use `pnpm` instead of `npm` or `yarn` for installing dependencies, running scripts, etc. (e.g., `pnpm install`, `pnpm run build`).
|
|
|
|
## Code Style
|
|
|
|
- Do not use emojis in code, output, or documentation. Unicode symbols (✓, ✗, →, ⚠) are acceptable.
|
|
- In documentation and markdown, never use double hyphens (`--`) as a dash. Use an emdash (—) sparingly when needed. Prefer rewriting the sentence to avoid dashes entirely.
|
|
- CLI colored output uses `cli/src/color.rs`. This module respects the `NO_COLOR` environment variable. Never use hardcoded ANSI color codes.
|
|
- CLI flags must always use kebab-case (e.g., `--auto-connect`, `--allow-file-access`). Never use camelCase for flags (e.g., `--autoConnect` is wrong).
|
|
|
|
## Documentation
|
|
|
|
When adding or changing user-facing features (new flags, commands, behaviors, environment variables, etc.), update **all** of the following:
|
|
|
|
1. `cli/src/output.rs` — `--help` output (flags list, examples, environment variables)
|
|
2. `README.md` — Options table, relevant feature sections, examples
|
|
3. `skill-data/core/SKILL.md` (and its `references/`) — so AI agents know about the feature when they load the core skill. Edit `skill-data/core/SKILL.md` for overview/workflow changes; edit `skill-data/core/references/*.md` for detailed reference content. Do **not** put feature content in `skills/agent-browser/SKILL.md` — that file is an intentionally thin discovery stub for `npx skills add` and exists only to redirect agents to `agent-browser skills get core`.
|
|
4. `docs/src/app/` — the Next.js docs site (MDX pages)
|
|
5. Inline doc comments in the relevant source files
|
|
|
|
This applies to changes that either human users or AI agents would need to know about. Do not skip any of these locations.
|
|
|
|
In the `docs/src/app/` MDX files, always use HTML `<table>` syntax for tables (not markdown pipe tables). This matches the existing convention across the docs site.
|
|
|
|
## Dashboard (packages/dashboard)
|
|
|
|
- Never use native browser dialogs (`alert`, `confirm`, `prompt`). Use shadcn/ui components (`Dialog`, `AlertDialog`, etc.) instead.
|
|
- Use param-case (kebab-case) for all file and folder names (e.g., `session-tree.tsx`, not `SessionTree.tsx`). The `ui/` directory follows shadcn conventions which already uses param-case.
|
|
|
|
## Releasing
|
|
|
|
Releases are manual, single-PR affairs. There is no changesets automation. The maintainer controls the changelog voice and format.
|
|
|
|
To prepare a release:
|
|
|
|
1. Create a branch (e.g. `prepare-v0.24.0`)
|
|
2. Bump `version` in `package.json`
|
|
3. Run `pnpm version:sync` to update `cli/Cargo.toml`, `cli/Cargo.lock`, and `packages/dashboard/package.json`
|
|
4. Write the changelog entry in `CHANGELOG.md` at the top, under a new `## <version>` heading, wrapped in `<!-- release:start -->` and `<!-- release:end -->` markers. Remove the `<!-- release:start -->` and `<!-- release:end -->` markers from the previous release entry so only the new release has markers.
|
|
5. Add a matching entry to `docs/src/app/changelog/page.mdx` at the top (below the `# Changelog` heading)
|
|
6. Open a PR and merge to `main`
|
|
|
|
When the PR merges, CI compares `package.json` version to what's on npm. If it differs, it builds all 7 platform binaries, publishes to npm, and creates the GitHub release automatically. The GitHub release body is extracted from the content between the `<!-- release:start -->` and `<!-- release:end -->` markers in `CHANGELOG.md`.
|
|
|
|
### Writing the changelog
|
|
|
|
Review the git log since the last release and write the entry in `CHANGELOG.md`. Follow the existing format and voice. Group changes under `### New Features`, `### Bug Fixes`, `### Improvements`, etc. Bold the feature/fix name, then describe it concisely. Reference PR numbers in parentheses.
|
|
|
|
Wrap the release notes (everything between the `## <version>` heading and the previous version) in markers so CI can extract them for the GitHub release. Only the current release should have markers; remove the `<!-- release:start -->` and `<!-- release:end -->` markers from any previous release entry:
|
|
|
|
```markdown
|
|
## 0.24.1
|
|
|
|
<!-- release:start -->
|
|
### Bug Fixes
|
|
|
|
- Fixed **baz** not working when qux is enabled (#1235)
|
|
|
|
### Contributors
|
|
|
|
- @ctate
|
|
<!-- release:end -->
|
|
|
|
## 0.24.0
|
|
|
|
### New Features
|
|
|
|
- **Foo command** - Added `foo` command for bar (#1234)
|
|
```
|
|
|
|
Include a `### Contributors` section listing the GitHub usernames (with `@` prefix) of everyone who contributed to the release. Check the git log between the previous tag and HEAD to find them.
|
|
|
|
Do not prefix entries with commit hashes. Do not use the changesets `### Patch Changes` / `### Minor Changes` headings. Use descriptive section names instead.
|
|
|
|
### Docs changelog
|
|
|
|
The docs changelog at `docs/src/app/changelog/page.mdx` mirrors `CHANGELOG.md` but uses a slightly different format. Each entry uses:
|
|
|
|
- A `v` prefix on the version (e.g. `## v0.24.0`)
|
|
- A date line with the full date: `<p className="text-[#888] text-sm">March 30, 2026</p>`
|
|
- A `---` separator between entries
|
|
|
|
Match the existing style in that file.
|
|
|
|
## Architecture
|
|
|
|
This is a Rust codebase. The browser automation daemon lives in `cli/src/native/` (daemon, actions, browser, CDP client, snapshot, state). The `--engine` flag selects Chrome vs Lightpanda. The `install` command downloads Chrome from Chrome for Testing directly.
|
|
|
|
## Testing
|
|
|
|
### Unit Tests
|
|
|
|
```bash
|
|
cd cli && cargo test
|
|
```
|
|
|
|
Runs all unit tests (~320 tests). These are fast and don't require Chrome.
|
|
|
|
### End-to-End Tests
|
|
|
|
```bash
|
|
cd cli && cargo test e2e -- --ignored --test-threads=1
|
|
```
|
|
|
|
Runs 18 e2e tests that launch real headless Chrome instances and exercise the full native daemon command pipeline. Requirements:
|
|
|
|
- Chrome must be installed
|
|
- Must run serially (`--test-threads=1`) to avoid Chrome instance contention
|
|
- Tests are `#[ignore]`'d so they don't run during normal `cargo test`
|
|
|
|
The e2e tests live in `cli/src/native/e2e_tests.rs` and cover: launch/close, navigation, snapshots, screenshots, form interaction, cookies, storage, tabs, element queries, viewport/emulation, domain filtering, diff, state management, error handling, and Phase 8 commands.
|
|
|
|
### Linting and Formatting
|
|
|
|
```bash
|
|
cd cli && cargo fmt -- --check # Check formatting
|
|
cd cli && cargo clippy # Lint
|
|
```
|
|
|
|
## Windows Debugging
|
|
|
|
A remote Windows Server 2022 EC2 instance is available for debugging Windows-specific issues. It uses AWS Systems Manager (SSM) with no SSH or open ports. Commands run via `aws ssm send-command` and return stdout/stderr.
|
|
|
|
### Prerequisites
|
|
|
|
The instance must be provisioned first (one-time, by a human):
|
|
|
|
```bash
|
|
./scripts/windows-debug/provision.sh
|
|
```
|
|
|
|
Requires: AWS CLI v2 configured with `ec2:*`, `iam:CreateRole`, `iam:AttachRolePolicy`, `ssm:SendCommand`, `ssm:GetCommandInvocation` permissions and a default VPC.
|
|
|
|
### Usage
|
|
|
|
Start the instance (if stopped):
|
|
|
|
```bash
|
|
./scripts/windows-debug/start.sh
|
|
```
|
|
|
|
Run a command on Windows:
|
|
|
|
```bash
|
|
./scripts/windows-debug/run.sh "<powershell-command>"
|
|
```
|
|
|
|
Sync the current git branch and rebuild:
|
|
|
|
```bash
|
|
./scripts/windows-debug/sync.sh
|
|
```
|
|
|
|
Stop the instance when done (avoids cost):
|
|
|
|
```bash
|
|
./scripts/windows-debug/stop.sh
|
|
```
|
|
|
|
### Common Workflows
|
|
|
|
Run unit tests on Windows:
|
|
|
|
```bash
|
|
./scripts/windows-debug/run.sh "cd C:\agent-browser && cargo test --manifest-path cli\Cargo.toml"
|
|
```
|
|
|
|
Run e2e tests on Windows:
|
|
|
|
```bash
|
|
./scripts/windows-debug/run.sh "cd C:\agent-browser && cargo test e2e --manifest-path cli\Cargo.toml -- --ignored --test-threads=1"
|
|
```
|
|
|
|
Check bootstrap progress (first boot only):
|
|
|
|
```bash
|
|
./scripts/windows-debug/run.sh "Get-Content C:\bootstrap.log"
|
|
```
|
|
|
|
The repo lives at `C:\agent-browser` on the instance. Rust, Git, and Chrome are pre-installed. The `run.sh` wrapper automatically adds cargo and git to PATH.
|
|
|
|
<!-- opensrc:start -->
|
|
|
|
## Source Code Reference
|
|
|
|
Source code for dependencies is available in `opensrc/` for deeper understanding of implementation details.
|
|
|
|
See `opensrc/sources.json` for the list of available packages and their versions.
|
|
|
|
Use this source code when you need to understand how a package works internally, not just its types/interface.
|
|
|
|
### Fetching Additional Source Code
|
|
|
|
To fetch source code for a package or repository you need to understand, run:
|
|
|
|
```bash
|
|
npx opensrc <package> # npm package (e.g., npx opensrc zod)
|
|
npx opensrc pypi:<package> # Python package (e.g., npx opensrc pypi:requests)
|
|
npx opensrc crates:<package> # Rust crate (e.g., npx opensrc crates:serde)
|
|
npx opensrc <owner>/<repo> # GitHub repo (e.g., npx opensrc vercel/ai)
|
|
```
|
|
|
|
<!-- opensrc:end -->
|