Browser automation (Playwright) Skill

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.

Inspect rendered DOM.

page.screenshot(path='outputs/inspect.png', full_page=True)
content = page.content()
page.locator('button').all()

Identify selectors from inspection results.
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

Agent Skills: Browser automation (Playwright)

Install this agent skill to your local

Skill Files