Browser Ladder

Climb the browser ladder — start free, escalate only when needed. L1 (fetch) → L2 (local Playwright) → L3 (BrowserCat) → L4 (Browserless.io for CAPTCHA/bot bypass).

Security Scan

The skill is internally coherent with its stated purpose (layered browser fallbacks); it behaves as described but has a few minor implementation and handling concerns you should be aware of before use.

Purpose & Capability

The ladder concept and requested binaries largely match the stated functionality: Docker is required for the Playwright rung and optional cloud services require API keys. Node is declared as required but the included runtime scripts (setup.sh, browse.sh) do not actually invoke node; Node is only used in the README examples. This is plausible (examples assume Node usage) but slightly disproportionate for the shipped scripts alone.

Instruction Scope

SKILL.md and scripts stay within the stated purpose: choose a rung, attempt curl/Docker/cloud, and return content/screenshots/PDFs. The setup script prompts for keys and writes them to a .env in the workspace; the browserless integration posts content to browserless endpoints. Nothing in the instructions asks the agent to read unrelated credentials or system files, but the setup modifies the workspace .env which can persist sensitive values.

Install Mechanism

No install spec is provided (instruction-only), so nothing arbitrary is downloaded or installed by the registry. The runtime uses standard public Docker images (mcr.microsoft.com/playwright) and curl; that is expected for Playwright-in-Docker usage.

Credentials

Only two optional credentials are declared (BROWSERCAT_API_KEY and BROWSERLESS_TOKEN) and both are relevant to Rungs 3–4. This is proportionate. Two handling concerns: (1) setup.sh writes keys in plaintext to a .env file in the workspace, which may be committed to source control if the workspace isn't protected; (2) browse.sh sends the Browserless token as a URL/query parameter in some requests (and SKILL.md shows the token in a WebSocket query string), which can be logged by intermediaries and increase token exposure risk.

Persistence & Privilege

always:false and normal invocation rights — no elevated or persistent platform privileges requested. The only persistent side-effect is storing optional API keys in the workspace .env via the setup script; the skill does not attempt to modify other skills or global agent configuration.

Assessment

This skill appears to do what it says (try curl → local Playwright via Docker → cloud fallbacks). Before installing or running it, consider: - The setup script will prompt for API keys and save them plaintext to .env in your workspace. Do not run it in a repository you might push to origin unless you first add .env to .gitignore or otherwise protect the file. Consider storing keys in a secret manager instead of a workspace .env. - Browserless token is passed in request URLs/WS query strings (and shown in examples). Tokens in URLs can be logged by proxies or servers; prefer sending tokens in headers if possible. Treat any supplied token as sensitive and rotate it if it may have been exposed. - BrowserCat code path is TODO/unimplemented in the provided script; Rung 3 will not work until implemented. - Node is declared as required but the provided scripts don't need it; if you won't use the Node examples you may not need Node installed. - The skill uses Docker and pulls a Playwright image—ensure your Docker daemon is secured and you trust the Playwright image source (mcr.microsoft.com). If you trust the author and follow the above precautions (protect .env, avoid committing secrets, prefer header-based auth where possible), the skill is reasonable to use. If you do not trust the source, avoid entering API keys or run the scripts in an isolated environment.

Climb from free to paid only when you need to.

Quick Setup

Run the setup script after installation:

./skills/browser-ladder/scripts/setup.sh

Or manually add to your .env:

# Optional - only needed for Rungs 3-4
BROWSERCAT_API_KEY=your-key    # Free: https://browsercat.com
BROWSERLESS_TOKEN=your-token   # Paid: https://browserless.io

The Ladder

┌─────────────────────────────────────────────┐
│  🪜 Rung 4: Browserless.io (Cloud Paid)     │
│  • CAPTCHA solving, bot detection bypass    │
│  • Cost: $10+/mo                            │
│  • Requires: BROWSERLESS_TOKEN              │
├─────────────────────────────────────────────┤
│  🪜 Rung 3: BrowserCat (Cloud Free)         │
│  • When local Docker fails                  │
│  • Cost: FREE (limited)                     │
│  • Requires: BROWSERCAT_API_KEY             │
├─────────────────────────────────────────────┤
│  🪜 Rung 2: Playwright Docker (Local)       │
│  • JavaScript rendering, screenshots        │
│  • Cost: FREE (CPU only)                    │
│  • Requires: Docker installed               │
├─────────────────────────────────────────────┤
│  🪜 Rung 1: web_fetch (No browser)          │
│  • Static pages, APIs, simple HTML          │
│  • Cost: FREE                               │
│  • Requires: Nothing                        │
└─────────────────────────────────────────────┘

Start at the bottom. Climb only when needed.

When to Climb

Situation	Rung	Why
Static HTML, APIs	1	No JS needed
React/Vue/SPA apps	2	JS rendering
Docker unavailable	3	Cloud fallback
CAPTCHA/Cloudflare	4	Bot bypass needed
OAuth/MFA flows	4	Complex auth

Decision Flow

Need to access a URL
         │
         ▼
    Static content? ──YES──▶ Rung 1 (web_fetch)
         │ NO
         ▼
    JS rendering only? ──YES──▶ Rung 2 (Playwright Docker)
         │ NO                        │
         │                     Success? ──NO──▶ Rung 3
         ▼                           │ YES
    CAPTCHA/bot detection? ────────────────────▶ DONE
         │ YES
         ▼
    Rung 4 (Browserless.io) ──▶ DONE

Usage Examples

Rung 1: Static content

// Built into Clawdbot
const content = await web_fetch("https://example.com");

Rung 2: JS-rendered page

docker run --rm -v /tmp:/output mcr.microsoft.com/playwright:v1.58.0-jammy \
  npx playwright screenshot https://spa-app.com /output/shot.png

Rung 3: Cloud browser (BrowserCat)

const { chromium } = require('playwright');
const browser = await chromium.connect('wss://api.browsercat.com/connect', {
  headers: { 'Api-Key': process.env.BROWSERCAT_API_KEY }
});

Rung 4: CAPTCHA bypass (Browserless)

const { chromium } = require('playwright');
const browser = await chromium.connectOverCDP(
  `wss://production-sfo.browserless.io?token=${process.env.BROWSERLESS_TOKEN}`
);
// CAPTCHA handled automatically

Cost Optimization

1. Start low — Always try Rung 1 first
2. Cache results — Don't re-fetch unnecessarily
3. Batch requests — One browser session for multiple pages
4. Check success — Only climb if lower rung fails

Get Your Keys

Service	Cost	Sign Up
BrowserCat	Free tier	https://browsercat.com
Browserless.io	$10+/mo	https://browserless.io

Both are optional — Rungs 1-2 work without any API keys.