New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Brd Browser Debug

by brightdata in brightdata/skills

Debug Bright Data Scraping Browser sessions using the Browser Sessions API.

MITAuto-check passedData & Analytics

Install Brd Browser Debug

skills CLI
$ npx skills add brightdata/skills --skill brd-browser-debug -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install brightdata/skills brd-browser-debug --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/brightdata/skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/brd-browser-debug .claude/skills/brd-browser-debug && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
brd-browser-debug
GitHub stars
264
Token cost
~2k tokens
SKILL.md length
868 words
Files
1
Skills in repo
14
Repo updated
First seen
Licence
MIT

At a glance

Debug Bright Data Scraping Browser sessions using the Browser Sessions API.

  • Works in 7 steps: Present a health summary: total from the… → Most recent session — always highlight… → Failed sessions — for each failure:… → …
  • The user encounters a Bright Data browser session error
  • SKILL.md covers Setup, Usage, Features and Diagnosing Failed Sessions
  • Reaches api.brightdata.com; needs BRIGHTDATA_API_KEY

What it does

Brd Browser Debug is an agent skill from brightdata/skills. Debug Bright Data Scraping Browser sessions using the Browser Sessions API. Use this skill when the user encounters a Bright Data browser session error, puppeteer stack trace, failed scraper run, or asks about session bandwidth, duration, captchas, or connection issues. Also use when a Bright Data scraper produces unexpected results such as empty data, 0 items found, missing products, or fewer results than expected — session data can reveal whether the issue is network/proxy-side (blocks, captchas, redirects…

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Data & Analytics, covering Web scraping, Debugging and Secrets management. It works with Bright Data and Puppeteer. The licence is MIT.

When your agent uses it

  • The user encounters a Bright Data browser session error
  • Puppeteer stack trace
  • Failed scraper run
  • Asks about session bandwidth

Example prompts

  • “why did my session fail”
  • “debug my bright data session”
  • “check my scraping browser sessions”
  • “/brd-browser-debug”

Requirements

  • A credential in BRIGHTDATA_API_KEY

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

  1. Present a health summary: total from the response, counts of finished / failed / running.
  2. Most recent session — always highlight it regardless of status (same detail level as single-session mode).
  3. Failed sessions — for each failure: session ID, timestamp, duration, bandwidth, then reason about the cause using the signals in the…
  4. Pattern detection — if 3+ sessions share the same error.code, call it a systemic issue
  5. Bandwidth outliers — group sessions by target_url domain. For each domain with 3+ sessions, calculate the median bandwidth. Flag any…
  6. Captcha activity — report how many sessions hit captchas and whether they were solved.
  7. Close with a one-line verdict: the most important finding and the most impactful fix.

What it can do on your machine

Read from SKILL.md and the folder at commit 81f51af. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are bash).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • api.brightdata.com

    Also links to:

    • docs.brightdata.com
    • brightdata.com
    • help.brightdata.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • BRIGHTDATA_API_KEY

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Brd Browser Debug loads about 2k tokens when it runs. Until then it costs about 249 tokens; SKILL.md has 868 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~249
When it runs · the whole SKILL.md, loaded when a task matches
~2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from brightdata/skills at commit 81f51af, republished under its MIT licence (© brightdata). 868 words, ~1,970 tokens.

Download SKILL.mdSave it as .claude/skills/brd-browser-debug/SKILL.md (or your agent's skills folder).
name
brd-browser-debug
description
Debug Bright Data Scraping Browser sessions using the Browser Sessions API. Use this skill when the user encounters a Bright Data browser session error, puppeteer stack trace, failed scraper run, or asks about session bandwidth, duration, captchas, or connection issues. Also use when a Bright Data scraper produces unexpected results such as empty data, 0 items found, missing products, or fewer results than expected — session data can reveal whether the issue is network/proxy-side (blocks, captchas, redirects, timeouts) or client-side (selectors, extraction logic). Triggers on phrases like 'why did my session fail', 'debug my bright data session', 'check my scraping browser sessions', 'how much bandwidth did my scraper use', 'got 0 results', 'found 0', 'scraper returned empty', 'scraper not working', 'script didn't work', or when a Bright Data error code or brd.superproxy.io stack trace appears in the conversation. Requires BRIGHTDATA_API_KEY environment variable.
user-invocable
true

Bright Data — Browser Session Debugger

Diagnose Bright Data Scraping Browser sessions using the Browser Sessions API. Fetches live session data and performs smart triage: error diagnosis, bandwidth analysis, captcha reporting, and pattern detection across recent sessions.

Setup

Set your API key:

bash
export BRIGHTDATA_API_KEY="your-api-key"

Get a key from Bright Data Dashboard → API Tokens.

No zone configuration needed — zone is returned as a field in session data.

Usage

List & triage recent sessions

Invoked as /brd-browser-debug with no arguments.

API reference: GET /browser_sessions

Fetching sessions

Start with a single call using limit=100 (the maximum) sorted by most recent:

GET https://api.brightdata.com/browser_sessions?limit=100&sort=timestamp&order=desc
Authorization: Bearer $BRIGHTDATA_API_KEY

Pagination: The response includes total, has_more, and next_offset. If has_more is true and the analysis requires more data (e.g. bandwidth outlier detection needs a larger sample), fetch the next page using offset=<next_offset>. Continue until you have enough data or has_more is false.

Available filters — apply when the user specifies a scope:

  • status=failed|finished|running — narrow to a specific session state
  • api_name=<zone> — filter to a specific Bright Data zone
  • target_url=<domain> — filter by target domain (e.g. ksp.co.il)
  • start_date / end_date — ISO 8601 datetime range
  • sort=timestamp|duration|bandwidth with order=asc|desc

If the user asks about a specific zone, date range, or domain — apply the relevant filter rather than fetching all sessions and filtering client-side.

Triage steps
  1. Present a health summary: total from the response, counts of finished / failed / running.
  2. Most recent session — always highlight it regardless of status (same detail level as single-session mode).
  3. Failed sessions — for each failure: session ID, timestamp, duration, bandwidth, then reason about the cause using the signals in the Diagnosing Failed Sessions section below.
  4. Pattern detection — if 3+ sessions share the same error.code, call it a systemic issue:

    "3 sessions failed with custom_headers — you are overriding a header Bright Data forbids. Remove page.setExtraHTTPHeaders() from your code."

  5. Bandwidth outliers — group sessions by target_url domain. For each domain with 3+ sessions, calculate the median bandwidth. Flag any session whose bandwidth exceeds 2× the median for that domain as an outlier, and note if it was a failed session that burned unusually high bandwidth before dying.
  6. Captcha activity — report how many sessions hit captchas and whether they were solved.
  7. Close with a one-line verdict: the most important finding and the most impactful fix.
Inspect a single session

Invoked as /brd-browser-debug <session_id>.

API reference: GET /browser_sessions/{session_id}

  1. Call:

    GET https://api.brightdata.com/browser_sessions/<session_id>
Authorization: Bearer $BRIGHTDATA_API_KEY

    Returns 404 if the session ID is not found — tell the user and stop.

  2. Present a deep-dive using the response fields:

    • Status (status): running / finished / failed
    • Zone (api_name): the Bright Data zone that handled the session
    • Timestamp (timestamp): ISO 8601 — show in local-friendly format
    • Duration (duration): seconds (nullable) — flag if < 2 s on failure (session barely started)
    • Bandwidth (bandwidth): convert bytes → MB
    • Navigations (navigations): flag if 0 (nothing was loaded)
    • Captcha (captcha): one of solved / none / detected / failed — detected means a challenge appeared but was not solved; failed means solving was attempted but unsuccessful
    • Route: target_url → end_url — note significant drift (different domain, login wall, error page)
    • Error (error.code + error.message): reason about the cause using the signals in Diagnosing Failed Sessions below

  3. Close with a one-line verdict.

Show full SKILL.md (359 more words)Show less
Auto-detect from conversation context

When a Bright Data browser issue appears in the conversation — including puppeteer stack traces, error codes, mention of brd.superproxy.io, the user describing a session failure, OR a scraper producing empty/unexpected results (e.g. "Found 0 categories", "Got 0 products", fewer items than expected):

  • If a session ID is visible in the output → run single-session deep-dive on it.
  • If no session ID is visible → run list & triage, filtering by the relevant target domain. Highlight the most recent session as the likely culprit.
  • Cross-reference the error or unexpected behavior seen in the conversation with what the API returns. A session that finished successfully with normal bandwidth but the scraper got 0 results points to a client-side selector/extraction bug, not a proxy issue.

Features

  • Smart triage: automatically groups sessions by failure pattern, not just lists them
  • Dynamic bandwidth outliers: compares sessions per domain using median, flags sessions exceeding 2× the median
  • Captcha reporting: shows captcha hit rate and solve rate
  • Error reasoning: reads session signals holistically to infer what went wrong
  • Zero config: reads API key from env var, no zone setup needed

Diagnosing Failed Sessions

Do not rely on the error code alone. Cross-reference all available session signals to reason about what went wrong:

  • Duration + navigations: a session that failed in < 2 s with 0 navigations never got past the connection phase — likely a configuration or auth issue. A session that ran for minutes before failing points to a runtime problem (blocked mid-scrape, idle timeout, network drop).
  • Bandwidth relative to other sessions: a failed session that consumed bandwidth similar to successful ones likely reached the target but failed during extraction. A failed session with near-zero bandwidth never loaded anything.
  • Captcha field: if captcha is detected but not solved, the session was stopped by an unsolved challenge — suggest enabling captcha solving on the zone.
  • target_url vs end_url: significant drift (different domain, login page, error page) means the session was redirected away from the intended target.
  • error.message: use the raw message text as-is to describe what happened — do not guess or invent meaning beyond what the message says. If the cause is unclear, direct the user to Bright Data support.

© brightdata, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/brd-browser-debug of brightdata/skills.

Open the folder on GitHubat commit 81f51af

Compare with similar skills

Brd Browser Debug next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Brd Browser Debug compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Brd Browser Debug this skillbrightdata/skills264—~2kAutomated safety check: PassMIT
Chrome Devtoolseinverne/dotfiles1211 repos~1.6kAutomated safety check: NotesApache-2.0
Optimize Button Patternsduckduckgo/tracker-radar-collector169—~1.6kAutomated safety check: PassCustom licence
Apify CLIapify/apify-cli255—~1.5kAutomated safety check: PassApache-2.0
Web Scrapercharlie-chann/ai-agent-langgraph-main114—~431Automated safety check: PassNone
Scrapedavila7/claude-code-templates32k—~392Automated safety check: PassMIT

Similar skills

  • Chrome Devtools

    einverne/dotfiles

    Browser automation, debugging, and performance analysis using Puppeteer CLI scripts.

    121 GitHub starsUsed in 1 repo~1.6k tokens
    Data & AnalyticsAuto-check: notes

  • Optimize Button Patterns

    duckduckgo/tracker-radar-collector

    Iteratively improves cookie-popup button regex patterns in button-patterns.js against labelled-button-texts.csv.

    169 GitHub stars~1.6k tokensUpdated yesterday
    Data & AnalyticsAuto-check passed

  • Apify CLI

    apify/apify-cli

    Official

    Patterns for invoking the Apify CLI (apify) from agents. An agent skill from apify/apify-cli.

    255 GitHub stars~1.5k tokensUpdated yesterday
    Data & AnalyticsAuto-check passed

  • Web Scraper

    charlie-chann/ai-agent-langgraph-main

    网页数据抓取专家。能提取网页正文、表格、列表、特定元素。适用于：竞品监控、价格追踪、结构化数据采集. An agent skill from charlie-chann/ai-agent-langgraph-main.

    114 GitHub stars~431 tokensUpdated 24 days ago
    Data & AnalyticsAuto-check passed

  • Scrape

    davila7/claude-code-templates

    Scrape any webpage as clean markdown via Bright Data Web Unlocker API.

    32k GitHub stars~392 tokensUpdated today
    Data & AnalyticsAuto-check passed

  • Crawlee

    LeoYeAI/openclaw-master-skills

    Expert guide for building web scrapers and crawlers using Crawlee (JavaScript/TypeScript and Python).

    2.2k GitHub stars~4.7k tokensUpdated 2 mo ago
    Data & AnalyticsAuto-check passed

More from brightdata/skills

All 14 skills in this repo

  • Design Mirror

    brightdata/skills

    Replicate the visual style of any website and apply it to your existing codebase.

    264 GitHub starsUsed in 1 repo~2.1k tokens
    Auto-check passed

  • Brightdata Proxy

    brightdata/skills

    Generate working code that routes HTTP requests through Bright Data proxy networks (Datacenter, ISP, Residential, Mobile) and help users decide which network and IP pool type to use (shared pool…

    264 GitHub stars~5.1k tokensUpdated yesterday
    Auto-check passed

  • Bright Data MCP

    brightdata/skills

    Bright Data MCP handles ALL web data operations. An agent skill from brightdata/skills.

    264 GitHub starsUsed in 1 repo~3.7k tokens
    Auto-check passed

  • Live Research

    brightdata/skills

    Produce a deep, multi-source, cited research brief on a topic from live web data using Bright Data's Discover API (intent-ranked web search + parsed page content).

    264 GitHub stars~1.8k tokensUpdated yesterday
    Auto-check passed

  • Brightdata SDK JS

    brightdata/skills

    Web data extraction and discovery using the Bright Data JavaScript/TypeScript SDK (@brightdata/sdk).

    264 GitHub stars~3k tokensUpdated yesterday
    Auto-check passed

  • Data Feeds

    brightdata/skills

    Extract structured data from 40+ supported platforms (Amazon, LinkedIn, Instagram, TikTok, Facebook, YouTube, Reddit, and more) via the Bright Data CLI (bdata pipelines).

    264 GitHub stars~2.2k tokensUpdated yesterday
    Auto-check passed

Works with

Categories

Questions about Brd Browser Debug

What does Brd Browser Debug do?

Debug Bright Data Scraping Browser sessions using the Browser Sessions API. Brd Browser Debug is an agent skill from brightdata/skills. Debug Bright Data Scraping Browser sessions using the Browser Sessions API.

When should I use Brd Browser Debug?

Brd Browser Debug fits situations like: the user encounters a Bright Data browser session error; puppeteer stack trace; failed scraper run; asks about session bandwidth.

How do I install Brd Browser Debug in Claude Code?

Run `npx skills add brightdata/skills --skill brd-browser-debug -a claude-code`. Or copy the skill folder (skills/brd-browser-debug in brightdata/skills) into .claude/skills/brd-browser-debug in your project. Claude Code loads it when a task matches its description.

How do I install Brd Browser Debug in Codex?

Run `npx skills add brightdata/skills --skill brd-browser-debug -a codex`. Or copy the skill folder (skills/brd-browser-debug in brightdata/skills) into .agents/skills/brd-browser-debug in your project. Codex loads it when a task matches its description.

Can I use Brd Browser Debug in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add brightdata/skills --skill brd-browser-debug -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/brd-browser-debug, .gemini/skills/brd-browser-debug, .github/skills/brd-browser-debug and .opencode/skills/brd-browser-debug in your project.

What does Brd Browser Debug need to run?

Going by SKILL.md and its folder, Brd Browser Debug needs credentials named BRIGHTDATA_API_KEY. Our summary lists: A credential in BRIGHTDATA_API_KEY.

Does Brd Browser Debug access the network?

SKILL.md names 4 domains. In commands or code: api.brightdata.com; the agent is likely to contact it when it follows the instructions. As links in the text: docs.brightdata.com, brightdata.com and help.brightdata.com. This is read from the text; nothing was executed.

Is Brd Browser Debug safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Brd Browser Debug use?

Brd Browser Debug is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Brd Browser Debug use?

About 2k tokens (SKILL.md is roughly 7.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Brd Browser Debug?

Skills that share tags, products or a category with Brd Browser Debug: Chrome Devtools (einverne/dotfiles, 121 stars), Optimize Button Patterns (duckduckgo/tracker-radar-collector, 169 stars), Apify CLI (apify/apify-cli, 255 stars) and Web Scraper (charlie-chann/ai-agent-langgraph-main, 114 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Brd Browser Debug?

brightdata (a GitHub organization) maintains it in brightdata/skills, which has 264 GitHub stars. The repository holds 14 skills in this directory. The repository was last updated on October 6, 2026.

Source: brightdata/skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.