Skill: wkenya/exa-research-openclaw-skill (version 0.1.0)

--- name: exa-research description: Use the local `exa` CLI to search the live web, ask grounded questions with citations, fetch page contents, find similar links, retrieve Exa code context, or manage Exa research tasks. Use when the task needs current web information, source-backed answers, URL/page extraction, related-link discovery, code examples from the web, or Exa-specific API access. Prefer this over generic web search when Exa highlights, answer synthesis, or research workflows are specifically useful. homepage: https://github.com/jdegoes/exa metadata: { "openclaw": { "emoji": "🔎", "requires": { "bins": ["exa"], "env": ["EXA_API_KEY"] }, "primaryEnv": "EXA_API_KEY", }, } --- # Exa Research Use the bundled wrapper to run Exa reliably: ```bash {baseDir}/scripts/exa-with-key.sh --help ``` ## Credentials Preferred OpenClaw-native setup: - `skills.entries.exa-research.apiKey` - or `skills.entries.exa-research.env.EXA_API_KEY` Other supported auth sources: - ambient `EXA_API_KEY` - `EXA_API_KEY_FILE` - default file fallback at `~/.openclaw/credentials/exa/api-key.txt` The wrapper prefers credentials in this order: 1. existing `EXA_API_KEY` 2. `EXA_API_KEY_FILE` 3. the default file path above ## Route to the smallest command that fits - Use `search` for live web discovery and filtered result lists. - Use `answer` for one grounded answer with citations. - Use `contents` when URLs or result IDs are already known and text/highlights/summary are needed. - Use `similar` when one seed URL is known and related pages are needed. - Use `context` for coding patterns, library usage, and implementation examples. - Use `research` for asynchronous or longer-running research workflows. - Use `raw` only when a higher-level command cannot express the request. ## Keep context lean - Start narrow; broaden only if recall is poor. - Prefer `answer` over manual search-plus-synthesis when the user wants a concise cited answer. - Prefer `highlights` before full `text` when excerpts are enough. - Cap payload size with `--text-max`, `--highlights-max`, and `context --tokens`. - Add domains, categories, and date filters early instead of retrieving broad result sets. - Do not dump large raw payloads into chat when a short synthesis will do. ## Command patterns ### Search ```bash {baseDir}/scripts/exa-with-key.sh "latest developments in llms" {baseDir}/scripts/exa-with-key.sh search --category news --include-domain reuters.com --highlights "AI regulation" {baseDir}/scripts/exa-with-key.sh search --type deep --additional-query "llm releases" "latest frontier models" ``` ### Answer ```bash {baseDir}/scripts/exa-with-key.sh answer "What is the latest valuation of SpaceX?" {baseDir}/scripts/exa-with-key.sh answer --text "What changed in the latest OpenAI release?" ``` ### Contents ```bash {baseDir}/scripts/exa-with-key.sh contents --text https://exa.ai {baseDir}/scripts/exa-with-key.sh contents --id doc-1 --id doc-2 --highlights {baseDir}/scripts/exa-with-key.sh contents --highlights --summary https://exa.ai https://example.com ``` ### Similar ```bash {baseDir}/scripts/exa-with-key.sh similar --highlights https://arxiv.org/abs/2307.06435 {baseDir}/scripts/exa-with-key.sh similar --text --text-max 3000 https://exa.ai/blog ``` ### Context ```bash {baseDir}/scripts/exa-with-key.sh context "React hooks for state management" {baseDir}/scripts/exa-with-key.sh context --tokens 5000 "pandas dataframe filtering and groupby operations" ``` ### Research ```bash {baseDir}/scripts/exa-with-key.sh research create "Summarize the latest developments in AI safety research" {baseDir}/scripts/exa-with-key.sh research list --limit 10 {baseDir}/scripts/exa-with-key.sh research get 01jszdfs0052sg4jc552sg4jc5 ``` ### Raw ```bash {baseDir}/scripts/exa-with-key.sh raw /search @payload.json {baseDir}/scripts/exa-with-key.sh raw -X GET '/research/v1?limit=10' printf '{"query":"latest llm news"}' | {baseDir}/scripts/exa-with-key.sh raw /search - ``` ## Practical guidance - Run `{baseDir}/scripts/exa-with-key.sh <subcommand> --help` before guessing flags. - If the task is exploratory, start with `search`, then escalate to `contents` only for selected URLs. - If the task is code-oriented, prefer `context` over broad search. - If the task needs longer-running synthesis, prefer `research` over ad hoc polling with `raw`. - If the user asks for the upstream generated skill text, run `exa skill`.

path: README.md
content: # exa-research-openclaw-skill

An OpenClaw-adapted skill for using the [`exa` CLI](https://github.com/jdegoes/exa) as a research/search workflow inside OpenClaw.

## What this repo is

This repository contains a reusable OpenClaw skill package built from the upstream Exa project's generated skill text plus OpenClaw-specific adaptations.

Contents:

- `SKILL.md` — the agent-facing skill instructions
- `scripts/exa-with-key.sh` — a wrapper that loads credentials securely and then runs `exa`
- `.gitignore` — basic repo-local junk-file ignores
- `LICENSE` — MIT license for this adaptation

## Upstream project

This skill is based on the upstream Exa project:

- Upstream repo: <https://github.com/jdegoes/exa>
- Upstream generated skill source: `exa skill`

The upstream project provides the Exa CLI itself, including the `exa skill` generator that emits a generic skill description.

## What changed from upstream

Compared with the raw upstream `exa skill` output, this OpenClaw version was adapted to:

- use OpenClaw-native metadata (`homepage`, `metadata.openclaw`, `primaryEnv`)
- use `{baseDir}` in skill instructions like mainstream OpenClaw skills do
- point usage at a bundled wrapper script instead of assuming `exa` is called directly
- support OpenClaw-native credential wiring via `skills.entries.exa-research.apiKey`
- keep the repo free of secrets
- focus documentation on OpenClaw-specific setup instead of duplicating upstream Exa install docs

## Prerequisites

- OpenClaw installed
- Exa CLI installed from the upstream Exa project
- a valid Exa API key
- `bash` and `curl`
- `jq` recommended (used by `exa diagnostics`)

## Install Exa

Follow the upstream Exa installation instructions:

- <https://github.com/jdegoes/exa>

This repo intentionally does **not** duplicate Exa installation steps. The only requirement here is that `exa` is installed and either:

- available on your `PATH`, or
- reachable via `EXA_BIN`

## Install this skill into OpenClaw

Install this repo into one of your OpenClaw skill directories using whatever skill layout your OpenClaw setup expects.

A common default is:

```bash
mkdir -p ~/.openclaw/skills
cp -R exa-research-openclaw-skill ~/.openclaw/skills/exa-research
chmod 700 ~/.openclaw/skills/exa-research/scripts/exa-with-key.sh
```

## Secure credential setup

This repo does **not** contain any API keys.

### Most idiomatic OpenClaw setup

Set the skill credential in OpenClaw config:

```json5
{
  skills: {
    entries: {
      "exa-research": {
        apiKey: { source: "file", provider: "exafile", id: "value" }
      }
    }
  }
}
```

Or set an explicit env entry:

```json5
{
  skills: {
    entries: {
      "exa-research": {
        env: {
          EXA_API_KEY: "..."
        }
      }
    }
  }
}
```

### Other supported auth sources

The wrapper supports auth in this order:

1. `EXA_API_KEY` already present in the environment
2. `EXA_API_KEY_FILE` pointing at a readable file
3. the default file path `~/.openclaw/credentials/exa/api-key.txt`

### Simple file-based setup

For personal/self-hosted installs, a locked-down file is also fine:

```bash
mkdir -p ~/.openclaw/credentials/exa
printf '%s\n' '<your-exa-api-key>' > ~/.openclaw/credentials/exa/api-key.txt
chmod 600 ~/.openclaw/credentials/exa/api-key.txt
```

You can also point somewhere else:

```bash
export EXA_API_KEY_FILE="$HOME/.config/exa/api-key.txt"
```

### Security notes

- never commit your API key
- keep key files outside the repo
- use `chmod 600` on file-based secrets
- prefer `skills.entries.exa-research.apiKey` or runtime env injection if you already use OpenClaw secrets or a secret manager

## Verify the setup

```bash
~/.openclaw/skills/exa-research/scripts/exa-with-key.sh diagnostics
~/.openclaw/skills/exa-research/scripts/exa-with-key.sh search -n 1 "latest OpenAI news"
```

## Intended use

This skill is meant to help OpenClaw choose Exa when a task needs:

- live web search
- grounded answers with citations
- page contents/highlights/summary
- similar-link discovery
- code context
- Exa research workflows

## Attribution

Credit for the Exa CLI, API surface, and the original generated skill text belongs to the upstream Exa project and its authors.


path: scripts/exa-with-key.sh
content: #!/usr/bin/env bash
set -euo pipefail

EXA_BIN="${EXA_BIN:-exa}"
EXA_API_KEY_FILE="${EXA_API_KEY_FILE:-$HOME/.openclaw/credentials/exa/api-key.txt}"

if [[ "$EXA_BIN" != */* ]]; then
  if ! EXA_BIN="$(command -v "$EXA_BIN" 2>/dev/null)"; then
    echo "Missing Exa binary on PATH: ${EXA_BIN:-exa}" >&2
    echo "Install Exa from the upstream project or set EXA_BIN to its full path." >&2
    exit 1
  fi
fi

if [[ ! -x "$EXA_BIN" ]]; then
  echo "Missing or non-executable Exa binary: $EXA_BIN" >&2
  exit 1
fi

# Preferred auth source order:
# 1. Existing EXA_API_KEY in the environment
# 2. EXA_API_KEY_FILE override
# 3. Default local credential file path
if [[ -z "${EXA_API_KEY:-}" ]]; then
  if [[ ! -f "$EXA_API_KEY_FILE" ]]; then
    cat >&2 <<EOF
Missing Exa credentials.

Provide one of:
- skills.entries.exa-research.apiKey (OpenClaw config)
- skills.entries.exa-research.env.EXA_API_KEY (OpenClaw config)
- EXA_API_KEY in the environment
- EXA_API_KEY_FILE pointing at a readable file
- the default file at: $EXA_API_KEY_FILE

Recommended file setup:
  mkdir -p "$(dirname "$EXA_API_KEY_FILE")"
  printf '%s\n' '<your-exa-api-key>' > "$EXA_API_KEY_FILE"
  chmod 600 "$EXA_API_KEY_FILE"
EOF
    exit 1
  fi

  if [[ ! -r "$EXA_API_KEY_FILE" ]]; then
    echo "Unreadable Exa API key file: $EXA_API_KEY_FILE" >&2
    exit 1
  fi

  EXA_API_KEY="$(head -n 1 "$EXA_API_KEY_FILE" | tr -d '\r\n')"
fi

if [[ -z "$EXA_API_KEY" ]]; then
  echo "Exa API key is empty. Set EXA_API_KEY, provide a non-empty key file, or configure skills.entries.exa-research.apiKey." >&2
  exit 1
fi

export EXA_API_KEY
exec "$EXA_BIN" "$@"


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)