home / skills / openclaw / skills / kagi-search

kagi-search skill

safe

/skills/silversteez/kagi-search

This skill helps you search the web using Kagi API to fetch current results with clean output and optional JSON.

npx playbooks add skill openclaw/skills --skill kagi-search

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

Files (3)

SKILL.md

2.2 KB

---
name: kagi-search
description: Web search using Kagi Search API. Use when you need to search the web for current information, facts, or references. Requires KAGI_API_KEY in the environment.
---

> **Note:** The Kagi Search API is currently in beta. To request API access, email [email protected]. You must be a Kagi subscriber to use the API.
---

# Kagi Search CLI

Web search using the Kagi Search API with a clean, readable output format.

## Quick Start

```bash
export KAGI_API_KEY="your_api_key"
kagi-search "your search query"
# or run directly:
python3 scripts/kagi-search.py "your search query"
```

## Features

- **Clean output** - Title, URL, snippet, and metadata for each result
- **Pagination support** - Control result count and offset
- **JSON mode** - Raw JSON output for scripting
- **Related searches** - Shows related queries (can be hidden)
- **API balance** - Displays remaining API quota
- **Fast & lightweight** - Pure Python, no dependencies

## Options

| Flag | Description |
|------|-------------|
| `query` | Search terms (required) |
| `-n, --limit` | Number of results (default: 10) |
| `-s, --offset` | Offset for pagination (default: 0) |
| `--json` | Output raw JSON |
| `--no-related` | Hide related searches |
| `-h, --help` | Show help |

## Examples

```bash
# Basic search
kagi-search "python async await tutorial"

# Limit results
kagi-search "AI news" --limit 5

# Pagination
kagi-search "recipes" --offset 10 --limit 5

# JSON for scripting
kagi-search "github stars" --json | jq '.data[].url'

# Hide related searches
kagi-search "rust programming" --no-related
```

## Setup

**Environment:**
```bash
export KAGI_API_KEY="your_api_key"
# Add to ~/.bashrc or ~/.zshrc for persistence
```

**PATH access:**
```bash
# Make executable and add to PATH
chmod +x scripts/kagi-search.py
cp scripts/kagi-search.py ~/.local/bin/kagi-search
```

## Requirements

- Python 3.7+
- `KAGI_API_KEY` environment variable
- Internet connection

## Output Format

```
[Query: search terms]
[Results: 5]
[API Balance: $0.123]
[Time: 45ms]
----------------------------------------
=== Result Title ===
https://example.com
Snippet text here...
[2024-01-15]
---
Related: related query 1, related query 2
```

Overview

This skill provides web search via the Kagi Search API with a clean, readable CLI-style output. It surfaces titles, URLs, snippets, metadata like date and API balance, and supports pagination and JSON output for scripting. Requires a KAGI_API_KEY set in the environment and a Kagi subscription for API access.

How this skill works

The skill sends queries to the Kagi Search API and formats results into a human-friendly block showing query, result count, API balance, timing, and each result's title, URL, snippet, and date. It can output raw JSON for automation, paginate via offset/limit, and optionally hide related searches. The tool is implemented in pure Python and runs with minimal dependencies.

When to use it

When you need current web facts or references not available in the agent’s training data.
When you want lightweight CLI access to search results with clear metadata.
When integrating search into scripts or pipelines using the JSON output.
When you need to paginate through large result sets or control offset/limit.
When you want to see related queries and remaining API quota at a glance.

Best practices

Set KAGI_API_KEY as an environment variable and keep it secret (do not commit it).
Use --json mode when integrating results into other tools or pipelines.
Paginate with offset/limit to avoid large single requests and manage quota.
Hide related searches (--no-related) for concise output in scripts.
Monitor API balance shown in output to avoid unexpected quota exhaustion.

Example use cases

Quickly look up a current tutorial or documentation page from the terminal.
Embed search results into automation: kagi-search 'query' --json | jq ...
Collect a list of URLs and snippets for research or content curation.
Browse related queries to expand or refine a research topic.
Batch-process searches with offset/limit to crawl results for archiving.

FAQ

How do I provide the API key?

Export KAGI_API_KEY in your shell (export KAGI_API_KEY="your_api_key") and ensure the process environment has access.

Do I need a Kagi subscription?

Yes. The Kagi Search API requires access which is available to Kagi subscribers and may be in beta.