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

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

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