# How to Diagnose Failing Browser Automations with the Site-Debugger Skill

> Troubleshoot broken browser automations effortlessly. The Site-Debugger skill analyzes failures, detects anti-bot measures, and provides actionable fixes for your remediation playbook.

- Repository: [browserbase/skills](https://github.com/browserbase/skills)
- Tags: how-to-guide
- Published: 2026-05-01

---

**The site-debugger skill automatically analyzes browser automation failures by launching an instrumented Chromium instance, detecting anti-bot measures, validating selectors, and generating a remediation playbook with actionable fixes.**

Browser automations built with Playwright or Selenium often fail silently due to anti-bot defenses, brittle selectors, or timing race conditions. The **site-debugger** skill in the `browserbase/skills` repository provides a systematic diagnostic workflow that captures full Chrome DevTools Protocol (CDP) traces and pinpoints exactly why your script broke.

## What the Site-Debugger Skill Diagnoses

The skill performs automated audits across five critical failure domains.

### Bot Detection and Anti-Automation Defenses

The analyzer detects **anti-bot scripts**, challenge pages (reCAPTCHA, hCAPTCHA), and browser fingerprinting techniques. When it identifies these defenses, it reports which specific mechanisms are blocking your automation and suggests workarounds such as extra headers or stealth plugins.

### Selector Stability and DOM Validation

The skill examines all CSS and XPath selectors used by your script, verifying they exist in the DOM and evaluating their stability. It flags **dynamic IDs**, hidden elements, or overly specific selectors that cause "element not found" errors, offering more robust alternatives.

### Timing, Network, and Resource Loading

It records page load timings, network stalls, and resource-load failures. This reveals **race conditions** or missing wait directives that cause intermittent failures when elements appear after your script attempts interaction.

### Authentication Flows and Session Handling

The debugger looks for login redirects, token-exchange flows, and session-cookie handling issues. It identifies missing authentication steps or cookie-sync problems that prematurely terminate sessions.

### CAPTCHA Detection and Classification

When a CAPTCHA appears, the skill reports its type (reCAPTCHA v2/v3, hCAPTCHA, etc.) and location in the DOM. This helps you decide whether to integrate a solver service or insert a manual intervention step.

## How the Site-Debugger Works Internally

According to the source code in [`skills/site-debugger/SKILL.md`](https://github.com/browserbase/skills/blob/main/skills/site-debugger/SKILL.md), the diagnostic pipeline executes in five stages:

1. **Launches a headless Chromium instance** instrumented with the `browser-trace` module ([`skills/browser-trace/SKILL.md`](https://github.com/browserbase/skills/blob/main/skills/browser-trace/SKILL.md)) to capture CDP events.
2. **Runs the supplied automation script** inside the traced browser, recording every network request, DOM mutation, and JavaScript execution.
3. **Analyzes the trace** using heuristic modules for bot detection, selector auditing, timing analysis, and authentication verification.
4. **Generates artifacts** in the output directory: [`report.json`](https://github.com/browserbase/skills/blob/main/report.json) containing the diagnostic findings, and [`playbook.yaml`](https://github.com/browserbase/skills/blob/main/playbook.yaml) containing verified remediation steps.
5. **Optionally uploads the trace** to the Browserbase UI for visual step-through debugging.

The core implementation reuses utilities from [`skills/functions/REFERENCE.md`](https://github.com/browserbase/skills/blob/main/skills/functions/REFERENCE.md) for selector analysis and timing heuristics.

## Running the Site-Debugger Skill

You can invoke the diagnostic via the Browserbase CLI or programmatically from a Node.js application.

### Using the Browserbase CLI

Install the CLI globally, then run the skill against your automation script:

```bash

# Install the CLI (once)

npm i -g @browserbase/cli

# Run the diagnosis

bb site-debugger run --script ./my-automation.js --output ./debug-output

```

The `--script` parameter points to your failing automation file, while `--output` specifies the directory where [`trace.json`](https://github.com/browserbase/skills/blob/main/trace.json), [`report.json`](https://github.com/browserbase/skills/blob/main/report.json), and [`playbook.yaml`](https://github.com/browserbase/skills/blob/main/playbook.yaml) will be written.

### Programmatic Implementation with Node.js

Import the `runSiteDebugger` function to embed diagnostics directly in your workflow:

```javascript
import { runSiteDebugger } from '@browserbase/skills/site-debugger';

const scriptPath = './my-automation.js';

runSiteDebugger({
  script: scriptPath,
  options: { timeoutMs: 30_000, stealth: true },
})
  .then(({ report, playbook, trace }) => {
    console.log('Diagnostic report:', report);
    console.log('Playbook saved to:', playbook.path);
  })
  .catch(err => {
    console.error('Site-debugger failed:', err);
  });

```

This returns JavaScript objects for the report, playbook metadata, and trace data, allowing you to programmatically inspect results before applying fixes.

## Applying Generated Playbooks to Fix Automations

The generated playbook contains concrete remediation steps. Apply them automatically using the `applyPlaybook` utility:

```javascript
import { applyPlaybook } from '@browserbase/skills/playbook';

const playbookPath = './debug-output/playbook.yaml';

applyPlaybook({ playbook: playbookPath })
  .then(() => console.log('Automation updated with fixes'))
  .catch(console.error);

```

The `applyPlaybook` function rewrites selectors, injects explicit waits, and adds missing authentication steps as specified in the playbook, transforming diagnostic findings into working code.

## Key Source Files and Architecture

The site-debugger skill is composed of the following source files:

- **[`skills/site-debugger/SKILL.md`](https://github.com/browserbase/skills/blob/main/skills/site-debugger/SKILL.md)**: Skill definition, entry point configuration, and option schema.
- **[`skills/browser-trace/SKILL.md`](https://github.com/browserbase/skills/blob/main/skills/browser-trace/SKILL.md)**: Shared tracing infrastructure that captures CDP logs for the debugger to analyze.
- **[`skills/functions/REFERENCE.md`](https://github.com/browserbase/skills/blob/main/skills/functions/REFERENCE.md)**: Helper utilities for DOM selector analysis, timing audits, and network inspection.
- **[`README.md`](https://github.com/browserbase/skills/blob/main/README.md)**: Repository overview table listing the site-debugger entry point and dependencies.

These files implement the instrumentation pipeline and public API used by both the CLI and programmatic SDK integrations.

## Summary

- The **site-debugger** skill systematically diagnoses Playwright and Selenium failures by analyzing bot detection, selector stability, network timing, authentication flows, and CAPTCHA challenges.
- It generates a **diagnostic report** ([`report.json`](https://github.com/browserbase/skills/blob/main/report.json)) and an actionable **playbook** ([`playbook.yaml`](https://github.com/browserbase/skills/blob/main/playbook.yaml)) that you can apply automatically to fix your automation.
- Invoke the skill via `bb site-debugger run` in the CLI or `runSiteDebugger()` in Node.js code.
- The implementation relies on [`skills/site-debugger/SKILL.md`](https://github.com/browserbase/skills/blob/main/skills/site-debugger/SKILL.md) and shares tracing components with [`skills/browser-trace/SKILL.md`](https://github.com/browserbase/skills/blob/main/skills/browser-trace/SKILL.md).

## Frequently Asked Questions

### What output files does the site-debugger skill generate?

The skill produces three primary artifacts in your specified output directory: [`trace.json`](https://github.com/browserbase/skills/blob/main/trace.json) containing the full CDP browser trace, [`report.json`](https://github.com/browserbase/skills/blob/main/report.json) containing the diagnostic analysis of failure points, and [`playbook.yaml`](https://github.com/browserbase/skills/blob/main/playbook.yaml) containing the concrete remediation steps to fix your script.

### How does the skill detect anti-bot mechanisms?

The analyzer inspects page scripts for known anti-automation signatures, evaluates browser fingerprinting attempts, and identifies challenge pages like reCAPTCHA or hCAPTCHA by analyzing DOM structure and network patterns defined in the [`skills/functions/REFERENCE.md`](https://github.com/browserbase/skills/blob/main/skills/functions/REFERENCE.md) heuristic modules.

### Can I use the site-debugger with existing Playwright or Selenium scripts?

Yes. The skill accepts any Node.js automation script as its `--script` parameter or `script` option. It wraps your existing Playwright or Selenium code in an instrumented Chromium instance, capturing execution behavior without requiring modifications to your underlying test logic.

### What is the difference between the report and the playbook?

The **report** ([`report.json`](https://github.com/browserbase/skills/blob/main/report.json)) is a diagnostic document describing what failed—such as which selectors were missing or which anti-bot defenses triggered. The **playbook** ([`playbook.yaml`](https://github.com/browserbase/skills/blob/main/playbook.yaml)) is an executable specification containing the actual fixes—such as updated selector strings, wait timeouts, and authentication steps—that the `applyPlaybook` function uses to rewrite your automation.