# Browser Use

> Skill for web browser automation using Playwright for both local and external URLs. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. Load with read_file on .kilocode/skills/browser-use/SKILL.md (ignore the absolute path in the location tag).

- Skill: `scottermonk/browser-use` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add scottermonk/browser-use`
- Raw SKILL.md: https://api.skillmd.com/api/skills/scottermonk/browser-use/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ScotterMonk (https://skillmd.com/u/scottermonk)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/scottermonk/browser-use

---


# Browser automation (Playwright)
Use native Python Playwright scripts to automate browsing and UI verification for any URL, including local development servers and external sites.

## Prerequisites
Read skill-local guidance only when `.kilocode/skills/browser-use/AGENTS.md` is confirmed to exist; otherwise use root `AGENTS.md` for project-specific Playwright installation notes, server commands, and local URLs.

**Helper scripts available** (all paths project-relative):
- `.kilocode/skills/browser-use/scripts/with_server.py` - Optional. Manages local dev server lifecycle (supports multiple servers).

**Always run scripts with `--help` first** to see usage. DO NOT read the source until you try running the script first and find that a customized solution is absolutely necessary. These scripts can be very large and thus pollute your context window. They exist to be called directly as black-box scripts rather than ingested into your context window.

**Output files**: Examples and scripts write screenshots/logs to an `outputs/` folder relative to the current working directory. The folder is created automatically if it does not exist.

## Decision tree: choosing your approach
```
User task → What is the target?
    ├─ Local HTML file (file://) → Read HTML file directly to identify selectors.
    │     💡 Use `Path(file).as_uri()` to get the correct `file:///` URL — never use `http://localhost/filename`.
    │     ├─ Success → Write Playwright script using selectors.
    │     └─ Fails/Incomplete → Treat as dynamic (below).
    └─ URL (http/https) → Do you control the server process?
          ├─ Yes (local dev server) → Is it already running?
          │     ├─ No → Run the local `.kilocode/skills/browser-use/scripts/with_server.py` helper with `--help`
          │     │        Then use the helper + write a simplified Playwright script.
          │     └─ Yes → Reconnaissance-then-action (below).
          └─ No (external site) → Reconnaissance-then-action (below).
```

## Example: using with_server.py (optional)
Use this only when you need to start and manage one or more local dev servers as part of automation.
`with_server.py` starts the server(s), waits until they are ready, runs your automation script, then cleans up. Run `--help` first before using it.

**Single server** (run from project root):
```
python .kilocode/skills/browser-use/scripts/with_server.py --server "<start command>" --port <port> -- python <automation-script>.py
```

**Multiple servers (e.g., backend + frontend)**:
```
python .kilocode/skills/browser-use/scripts/with_server.py `
  --server "<backend start command>" --port <backend-port> `
  --server "<frontend start command>" --port <frontend-port> `
  -- python <automation-script>.py --url <url>
```

Your automation script only needs Playwright logic — servers are managed automatically by `with_server.py`.
See this skill folder's examples for robust, ready-to-use boilerplate.

## Reconnaissance-Then-Action Pattern
💡 **Tip for Users:** You can rapidly generate selectors and scripts by running `playwright codegen <url>` in your terminal.

1) **Inspect rendered DOM**.
    ```python
    page.screenshot(path='outputs/inspect.png', full_page=True)
    content = page.content()
    page.locator('button').all()
    ```
2) **Identify selectors** from inspection results.
3) **Execute actions** using discovered selectors.

## Common Pitfall
❌ **Don't** rely on `networkidle` as it is flaky on modern apps with background polling.
✅ **Do** wait for a specific element to be visible: `page.wait_for_selector('.main-content')` before inspection.
❌ **Don't** use operating-system-specific temp paths unless the project guidance confirms them.
✅ **Do** use a relative `outputs/` directory (auto-created by examples).
❌ **Don't** default to `async_playwright` — async adds complexity without benefit for one-off automation scripts.
✅ **Do** use `sync_playwright()` (synchronous) unless you have an explicit reason to use async (e.g., integrating with an async framework).

## Best Practices
- **Use bundled scripts as black boxes** - To accomplish a task, consider whether one of the scripts available in this skill folder's `scripts/` directory can help. These scripts handle common, complex workflows reliably without cluttering the context window. Use `--help` to see usage, then invoke directly.
- Use `sync_playwright()` for synchronous scripts
- Always close the browser when done (use `try/finally`)
- Use descriptive selectors: `text=`, `role=`, CSS selectors, or IDs
- Add appropriate waits: `page.wait_for_selector()` — not `networkidle`
- Output files go in a relative `outputs/` directory; create it with `Path('outputs').mkdir(parents=True, exist_ok=True)`

## Reference Files

All paths below are project-relative.

- **scripts/** - Helper scripts (call with `--help` first; do NOT read source):
  - `.kilocode/skills/browser-use/scripts/with_server.py` - Starts one or more local dev servers, runs your automation script, then cleans up

- **examples/** - Automation scripts (pass these to `with_server.py` or run standalone):
  - `.kilocode/skills/browser-use/examples/basic_automation.py` - Robust boilerplate with error handling and `wait_for_selector`
  - `.kilocode/skills/browser-use/examples/element_discovery.py` - Discovering buttons, links, and inputs on a page
  - `.kilocode/skills/browser-use/examples/static_html_automation.py` - Using file:// URLs for local HTML
  - `.kilocode/skills/browser-use/examples/console_logging.py` - Capturing console logs during automation