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
organicarray withtitle,linkanddescriptionfor each hit) - Pagination (an optional 0-indexed page number:
1returns results 11 to 20) - One readable script (about 50 lines of bash built on
curlandjq, 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
/searchyourself)
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
organicarray 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