home / skills / michalvavra / agents / brave-search

brave-search skill

safe

/skills/brave-search

This skill retrieves web results using Brave Search to enhance lookup accuracy and speed for AI agents.

npx playbooks add skill michalvavra/agents --skill brave-search

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.1 KB

---
name: brave-search
description: Web search via the Brave Search API. Use to retrieve search results from Brave when web lookups are needed.
compatibility: Requires BRAVE_SEARCH_API_KEY and uv with Python 3.12+ for scripts/brave-search.py.
---

# Brave Search

## Quick start

```bash
export BRAVE_SEARCH_API_KEY="your-token"
{baseDir}/scripts/brave-search.py "pi coding agent" --search-lang en --country US
```

## Usage

```bash
{baseDir}/scripts/brave-search.py "QUERY" [OPTIONS]
uv run --script {baseDir}/scripts/brave-search.py "QUERY" [OPTIONS]
```

## Options

- `--count <N>`: Maximum results to return (default: 5)
- `--offset <N>`: Offset into the result set (default: 0)
- `--country <CODE>`: Two letter country code
- `--search-lang <CODE>`: Search language code
- `--safesearch <off|moderate|strict>`: Safe search mode
- `--freshness <day|week|month>`: Filter by recency
- `--json`: Output normalized JSON
- `--raw`: Output raw API response
- `--help`: Show help

## Environment variables

```bash
BRAVE_SEARCH_API_KEY="your-token"
```

## Examples

```bash
{baseDir}/scripts/brave-search.py "observability tools" --count 3
```

Overview

This skill provides web search via the Brave Search API to retrieve up-to-date search results when web lookups are needed. It wraps the API in a simple CLI with options for count, country, language, safesearch, and freshness. Use it to fetch normalized JSON or raw API responses for downstream processing. The skill requires a Brave Search API key in the environment.

How this skill works

The skill calls the Brave Search API using an API key read from the BRAVE_SEARCH_API_KEY environment variable. It supports query parameters like count, offset, country, search language, safesearch level, and freshness to shape results. Output can be normalized JSON for programmatic use or raw API responses for debugging. The CLI can be invoked directly or through simple script runners.

When to use it

When you need live web search results integrated into an agent workflow.
To gather up-to-date information or links for research, summarization, or fact-checking.
When you need control over result count, regional targeting, language, or safe-search filtering.
For programmatic retrieval of search results in JSON for downstream parsing or scoring.
When debugging search queries and you want the raw API response.

Best practices

Set BRAVE_SEARCH_API_KEY in your environment to avoid exposing credentials in command lines or scripts.
Use --count and --offset to paginate results and reduce payload size for large queries.
Specify --country and --search-lang to get region- and language-relevant results.
Prefer --json for predictable, normalized output that is easy to parse programmatically.
Use --raw only when you need the full API response for debugging or auditing.

Example use cases

Fetch top 3 search results for tool research: run the CLI with --count 3 and parse JSON for links and snippets.
Regional content checks: use --country US and --search-lang en to compare search results across markets.
Content freshness filtering: set --freshness day or week to surface recent news or updates.
Safe-search enforcement: run queries with --safesearch strict for content-moderated outputs.
Automated fact-checking pipeline: retrieve search hits as JSON and pass them to a scoring component for relevance and evidence extraction.

FAQ

How do I provide the API key?

Export BRAVE_SEARCH_API_KEY in your shell before running the CLI, e.g. export BRAVE_SEARCH_API_KEY="your-token". The script reads this environment variable at runtime.

What output formats are available?

Use --json to get normalized JSON suitable for parsing, or --raw to receive the full raw API response for debugging. Default CLI output is a human-friendly summarized form when neither flag is used.