Bright Data Search Skill for Claude Code

What is the Bright Data Search Skill?

The Search skill gives Claude Code a way to query Google and read the answer as data. It ships a small bash script that sends your query through the Bright Data SERP API and prints a compact JSON object with an organic array: one entry per result, each with a title, a link and a description. No HTML to parse, no ads or widgets to filter out.

graph LR
    A[💬 Your question] --> B[🔎 Search skill]
    B --> C[⚡ Bright Data SERP API]
    C --> D[✅ JSON: title, link, description]

    style B fill:#F97316,stroke:#fff,color:#000
                    

Key Capabilities

  • Structured results (an organic array with title, link and description for each hit)
  • Pagination (an optional 0-indexed page number: 1 returns results 11 to 20)
  • One readable script (about 50 lines of bash built on curl and jq, easy to audit)
  • Clear failure messages (the script stops and says which variable is missing instead of calling the API)
  • Model or manual invocation (Claude can pick it up when a task needs a web search, or you can call /search yourself)

Installation

Install the skill using the Claude Code Templates CLI:

npx claude-code-templates@latest --skill web-data/search

Where is the skill installed?

Skills are saved in the .claude/skills/ directory of your project, one folder per skill:

your-project/
├── .claude/
│   └── skills/
│       └── search/
│           ├── SKILL.md          # ← Instructions Claude reads
│           └── scripts/
│               └── search.sh     # ← The script that calls the API
├── src/
└── package.json

The script needs curl and jq on your PATH, plus a Bright Data account. Searches go through your Bright Data zone and are billed by Bright Data according to your plan.

How It Works

The script builds a Google search URL from your query, posts it to https://api.brightdata.com/request with your zone name and data_format: "parsed_light", and then uses jq to keep only the organic results that have both a link and a title:

{
  "organic": [
    {
      "link": "https://example.com/article",
      "title": "Article Title",
      "description": "Brief description of the page..."
    }
  ]
}

Two environment variables drive it: BRIGHTDATA_API_KEY (sent as a Bearer token) and BRIGHTDATA_UNLOCKER_ZONE (the name of your Web Unlocker zone).

Step-by-Step Workflow

Step 1: Install the skill

cd your-project
npx claude-code-templates@latest --skill web-data/search

Step 2: Create a Bright Data key and zone

In the Bright Data control panel, copy your API key, then click "Add" and create an "Unlocker zone". Note the zone name: the script needs it.

Step 3: Give Claude Code the two variables

Either export them in the shell before starting Claude Code:

export BRIGHTDATA_API_KEY="your-api-key"
export BRIGHTDATA_UNLOCKER_ZONE="your-zone-name"

Or put them in .claude/settings.local.json, the personal settings file that is meant to stay out of git (add it to .gitignore if you create it by hand). Never put the key in the shared .claude/settings.json:

{
  "env": {
    "BRIGHTDATA_API_KEY": "your-api-key",
    "BRIGHTDATA_UNLOCKER_ZONE": "your-zone-name"
  }
}

Step 4: Test the script on its own

Run it from the project root before involving Claude, so you know the key and the zone work. A plain terminal does not read .claude/settings.local.json, so export both variables in that shell first (Step 3), or run the same command from inside Claude Code with the ! prefix:

bash .claude/skills/search/scripts/search.sh "claude code hooks documentation"

# Page 2 of the same query
bash .claude/skills/search/scripts/search.sh "claude code hooks documentation" 1

The skill's own instructions write the command as bash scripts/search.sh, relative to the skill folder. Claude Code runs shell commands from your project directory, so the full path above is the one that resolves from the root.

Step 5: Ask Claude to search

claude

> Search Google for the latest Astro 5 migration guides and summarize the top three results with their links

Claude sees the skill's description, loads SKILL.md when the task calls for a search, runs the script and works from the JSON. You can also invoke it directly:

> /search "astro 5 migration guide"

If .claude/skills/ did not exist when the session started, run /reload-skills or restart Claude Code so the new skill is picked up.

Step 6: Skip the permission prompt (optional)

Claude asks before running a shell command it has not been allowed to run. To approve this script once and for all, add a rule to .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(bash .claude/skills/search/scripts/search.sh *)"
    ]
  }
}

Permission rules match the command text, so keep the rule in the same form Claude uses to call the script.

A Practical Use Case

Search becomes useful when it feeds the next step of a task. A few prompts that work well:

  • Dependency research: "Search for known issues upgrading Tailwind v3 to v4 and list the breaking changes that affect this repo."
  • Error triage: "Search for this exact error message and tell me which of the top results match our stack."
  • Source gathering: "Find five recent articles on Postgres connection pooling and write the links and one-line summaries to docs/research.md."

The results contain titles, links and short descriptions only. When Claude needs the content of a page, pair this skill with its sibling, web-data/scrape, which fetches a URL as markdown through the same Bright Data zone:

npx claude-code-templates@latest --skill web-data/search,web-data/scrape

Tips

  • An empty organic array usually means the API returned an error instead of results: check the zone name and the key first.
  • Ask for a specific number of results or pages so Claude does not page further than the task needs: each page is one billed request.
  • Search results are untrusted text. Review what Claude plans to do with a page before letting it act on instructions found there.

Official Documentation

For more information about skills in Claude Code, see the official skills documentation. The skill comes from the Bright Data skills repository.

Created by Daniel Ávila

Explore 800+ Claude Code Components

Discover agents, commands, MCPs, settings, hooks, skills and templates to supercharge your Claude Code workflow

Browse All Components
Back to Blog