Brave Search API Skills

Official skills for using Brave Search API with AI coding agents.

Works with Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, VS Code, Windsurf, OpenClaw, Cline, Goose, Amp, Roo Code, and many other agents that support the Agent Skills standard.

Prerequisites · Installation · Available Skills · Quick Start · Goggles · Documentation

Prerequisites

Get a Brave Search API key at https://api.search.brave.com

Security tip: Prefer agent-native config over shell profile exports. Coding agents can access environment variables — scoped configs limit exposure. See API key setup for all options.

Claude Code

Add to ~/.claude/settings.json (docs):

{
  "env": {
    "BRAVE_SEARCH_API_KEY": "your-key"
  }
}

This makes the key available in all Claude Code sessions. For per-project use, add to .claude/settings.local.json (gitignored) with the same format.

Cursor

Option 1 — direnv (directory-scoped, auto-loads/unloads):

# Install direnv (https://direnv.net), then in your project directory:
echo 'export BRAVE_SEARCH_API_KEY="your-key"' >> .envrc
direnv allow

Option 2 — Shell profile (~/.zshrc or ~/.bashrc):

export BRAVE_SEARCH_API_KEY="your-key"

Then restart Cursor (launch from terminal or fully quit and reopen — reloading the window is not enough). Cursor inherits environment variables from your shell. You can also add skills via Settings > Rules > Add Rule > Remote Rule using the GitHub URL.

Codex

Option 1 — config.toml (docs):

# ~/.codex/config.toml
[shell_environment_policy]
set = { BRAVE_SEARCH_API_KEY = "your-key" }

Option 2 — Shell profile (~/.zshrc or ~/.bashrc):

export BRAVE_SEARCH_API_KEY="your-key"

Then restart your terminal. Codex reads environment variables from the shell (CLI, app, and IDE extension).

OpenClaw

Add to ~/.openclaw/.env (docs):

BRAVE_SEARCH_API_KEY=your-key

Or add to ~/.openclaw/openclaw.json under the skill's config:

{
  "skills": {
    "entries": {
      "brave-search": {
        "env": {
          "BRAVE_SEARCH_API_KEY": "your-key"
        }
      }
    }
  }
}

Other agents

Option 1 — direnv (directory-scoped, auto-loads/unloads):

# Install direnv (https://direnv.net), then in your project directory:
echo 'export BRAVE_SEARCH_API_KEY="your-key"' >> .envrc
direnv allow

Option 2 — Shell profile (~/.zshrc or ~/.bashrc):

export BRAVE_SEARCH_API_KEY="your-key"

Installation

All agents below support the Agent Skills standard and read SKILL.md files from their skills directory.

Claude Code

Skills documentation

Plugin marketplace (auto-updates, no git needed):

/plugin marketplace add brave/brave-search-skills
/plugin install brave-search-skills@brave-search

curl (no git, no marketplace):

# User-level (available in all projects)
mkdir -p ~/.claude/skills && curl -sL https://github.com/brave/brave-search-skills/archive/main.tar.gz | tar xz -C ~/.claude/skills --strip-components=2 brave-search-skills-main/skills

# Project-level
mkdir -p .claude/skills && curl -sL https://github.com/brave/brave-search-skills/archive/main.tar.gz | tar xz -C .claude/skills --strip-components=2 brave-search-skills-main/skills

Manual (git clone + cp):

git clone https://github.com/brave/brave-search-skills
cp -r brave-search-skills/skills/* ~/.claude/skills/   # user-level
cp -r brave-search-skills/skills/* .claude/skills/      # project-level

Cursor

Skills documentation

Remote Rule (no terminal needed):

Settings → Rules → Project Rules → Add Rule → Remote Rule → paste https://github.com/brave/brave-search-skills

curl:

# Project-level
mkdir -p .cursor/skills && curl -sL https://github.com/brave/brave-search-skills/archive/main.tar.gz | tar xz -C .cursor/skills --strip-components=2 brave-search-skills-main/skills

# User-level
mkdir -p ~/.cursor/skills && curl -sL https://github.com/brave/brave-search-skills/archive/main.tar.gz | tar xz -C ~/.cursor/skills --strip-components=2 brave-search-skills-main/skills

Manual (cp — requires git clone above):

cp -r brave-search-skills/skills/* .cursor/skills/      # project-level
cp -r brave-search-skills/skills/* ~/.cursor/skills/     # user-level

Cursor natively reads skills from .cursor/skills/, .claude/skills/, and .codex/skills/ at both project and user level.

GitHub Copilot

curl:

mkdir -p .github/skills && curl -sL https://github.com/brave/brave-search-skills/archive/main.tar.gz | tar xz -C .github/skills --strip-components=2 brave-search-skills-main/skills

Manual (cp — requires git clone above):

cp -r brave-search-skills/skills/* .github/skills/

Codex

Skills documentation

Skill installer (built-in — ask Codex to install skills from https://github.com/brave/brave-search-skills).

curl:

# User-level
mkdir -p ~/.agents/skills && curl -sL https://github.com/brave/brave-search-skills/archive/main.tar.gz | tar xz -C ~/.agents/skills --strip-components=2 brave-search-skills-main/skills

# Project-level
mkdir -p .agents/skills && curl -sL https://github.com/brave/brave-search-skills/archive/main.tar.gz | tar xz -C .agents/skills --strip-components=2 brave-search-skills-main/skills

Manual (cp — requires git clone above):

cp -r brave-search-skills/skills/* ~/.agents/skills/    # user-level
cp -r brave-search-skills/skills/* .agents/skills/       # project-level

Codex reads from .agents/skills/ at repo, parent, root, and user levels. Skills work across the CLI, desktop app, and IDE extension.

Windsurf

curl:

# Project-level
mkdir -p .windsurf/skills && curl -sL https://github.com/brave/brave-search-skills/archive/main.tar.gz | tar xz -C .windsurf/skills --strip-components=2 brave-search-skills-main/skills

# User-level
mkdir -p ~/.codeium/windsurf/skills && curl -sL https://github.com/brave/brave-search-skills/archive/main.tar.gz | tar xz -C ~/.codeium/windsurf/skills --strip-components=2 brave-search-skills-main/skills

Manual (cp — requires git clone above):

cp -r brave-search-skills/skills/* .windsurf/skills/             # project-level
cp -r brave-search-skills/skills/* ~/.codeium/windsurf/skills/   # user-level

OpenClaw

Skills documentation

curl:

mkdir -p ~/.openclaw/skills && curl -sL https://github.com/brave/brave-search-skills/archive/main.tar.gz | tar xz -C ~/.openclaw/skills --strip-components=2 brave-search-skills-main/skills

Manual (cp — requires git clone above):

cp -r brave-search-skills/skills/* ~/.openclaw/skills/

Other Agents (Cline, Gemini CLI, Goose, Amp, Roo Code, etc.)

curl (adjust the target directory for your agent):

mkdir -p <skills-dir> && curl -sL https://github.com/brave/brave-search-skills/archive/main.tar.gz | tar xz -C <skills-dir> --strip-components=2 brave-search-skills-main/skills

Or copy skills from a git clone to the agent's skills directory. All agents following the Agent Skills standard read SKILL.md files from their skills folder.

OpenSkills (Third-Party Universal Installer)

npx openskills install brave/brave-search-skills

See openskills on GitHub for details.

Updating

Claude Code marketplace: updates automatically, or run /plugin marketplace update brave-search.

curl: re-run the curl command above to overwrite with the latest version.

git clone: pull the latest changes and re-copy:

cd brave-search-skills && git pull
cp -r skills/* ~/.claude/skills/    # Claude Code
cp -r skills/* .cursor/skills/      # Cursor
cp -r skills/* .agents/skills/      # Codex
cp -r skills/* ~/.openclaw/skills/  # OpenClaw

Or re-run the OpenSkills install command to overwrite with the latest version.

See the full list of compatible agents at agentskills.io.

Available Skills

Skill	Description	Endpoint	Best For
llm-context	Pre-extracted web content for LLM grounding (GET/POST)	`/res/v1/llm/context`	RAG, AI agents — recommended
answers	AI-grounded answers, OpenAI SDK compatible	`/res/v1/chat/completions`	Chat interfaces, cited answers
web-search	Ranked web results with snippets and rich data	`/res/v1/web/search`	General search queries
images-search	Image search with thumbnails (up to 200 results)	`/res/v1/images/search`	Finding images
news-search	News articles with freshness filtering	`/res/v1/news/search`	Current events, breaking news
videos-search	Video search with duration/views/creator	`/res/v1/videos/search`	Finding video content
local-pois	Local business/POI details (ratings, hours, contact)	`/res/v1/local/pois`	Business info from POI IDs
local-descriptions	AI-generated POI text descriptions	`/res/v1/local/descriptions`	POI summaries from POI IDs
suggest	Query autocomplete (<100ms response)	`/res/v1/suggest/search`	Search UX, query expansion
spellcheck	Spell correction for query cleanup	`/res/v1/spellcheck/search`	Query preprocessing

Quick Start

LLM Context (Recommended for AI)

Returns search results with pre-extracted web content, optimized for LLM grounding:

curl -X GET "https://api.search.brave.com/res/v1/llm/context?q=search+API+for+grounding+LLMs" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

Web Search

Standard search with snippets, URLs, and metadata:

curl -s "https://api.search.brave.com/res/v1/web/search?q=retrieval+augmented+generation+explained" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

Answers (AI-Grounded)

OpenAI SDK-compatible endpoint for AI-grounded answers with citations.

Fast single-search (blocking):

curl -X POST "https://api.search.brave.com/res/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -d '{
    "messages": [{"role": "user", "content": "What programming languages are trending in 2026?"}],
    "model": "brave",
    "stream": false
  }'

Research mode (streaming required):

curl -X POST "https://api.search.brave.com/res/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -d '{
    "messages": [{"role": "user", "content": "How are developers building AI-powered search applications in 2026?"}],
    "model": "brave",
    "stream": true,
    "enable_research": true
  }'

Goggles (Custom Ranking)

Brave's unique feature lets you filter, boost, or downrank results:

# Focus on specific domains only
curl -X GET "https://api.search.brave.com/res/v1/llm/context" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=rust programming" \
  --data-urlencode 'goggles=$discard
$site=docs.rs
$site=rust-lang.org'

Learn more: https://search.brave.com/help/goggles

Documentation

API Reference: https://api.search.brave.com/docs
Goggles Quickstart: https://github.com/brave/goggles-quickstart
Rate Limits: Check your API plan at https://api.search.brave.com
Agent Skills Standard: https://agentskills.io/specification
Claude Code Skills: https://code.claude.com/docs/en/skills
Cursor Skills: https://cursor.com/docs/context/skills
Codex Skills: https://developers.openai.com/codex/skills
OpenClaw Skills: https://docs.openclaw.ai/tools/skills

License

MIT