# kagi-search

> Search the web using Kagi's premium ad-free search engine, summarize web pages/PDFs/videos, and get AI-powered answers. Use when the user needs current information, wants to summarize a URL, or asks questions requiring web research. Kagi provides high-quality, unbiased results without SEO spam.

- Author: hffmnnj
- Repository: hffmnnj/kagi-skill
- Version: 20251222001237
- Stars: 4
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/hffmnnj/kagi-skill
- Web: https://mule.run/skillshub/@@hffmnnj/kagi-skill~kagi-search:20251222001237

---

---
name: kagi-search
description: Search the web using Kagi's premium ad-free search engine, summarize web pages/PDFs/videos, and get AI-powered answers. Use when the user needs current information, wants to summarize a URL, or asks questions requiring web research. Kagi provides high-quality, unbiased results without SEO spam.
dependencies:
  - httpx>=0.27.0
  - pydantic>=2.0.0
---

# Kagi Search Skill

## Overview

This skill provides access to Kagi's premium search APIs, offering:
- **Search**: Ad-free web search with personalization
- **FastGPT**: AI-powered answers with citations ($0.015/query)
- **Summarizer**: Summarize URLs, PDFs, videos, audio ($0.03/1K tokens)
- **Enrichment**: Discover indie/small web content ($0.002/search)

All APIs support caching - identical queries return cached results for free.

## When to Use This Skill

Invoke this skill when:
- User asks about current events, recent information, or real-time data
- User provides a URL to summarize or analyze
- User needs factual answers requiring web research
- User wants to find indie/alternative content sources
- User is comparing information across multiple sources

Do NOT use for:
- Information clearly within your knowledge cutoff
- Simple calculations or code generation
- Questions about local files or codebases

## API Selection Decision Tree

Choose the right API based on the user's needs and optimize for cost:

### Use FastGPT (`scripts/fastgpt.py`)

**Cost**: $0.015 per query (cheapest for Q&A)

**When to use**:
- User asks a direct question with a factual answer
  - "What is quantum computing?"
  - "When did the event happen?"
  - "How does technology X work?"
- Speed and cost matter more than comprehensive sources
- A single authoritative answer suffices
- User wants quick facts, not deep research

**Command format**:
```bash
python scripts/fastgpt.py "What is quantum computing?"
```

### Use Search (`scripts/search.py`)

**Cost**: $0.025 per query

**When to use**:
- User needs multiple sources or perspectives
- Researching a topic broadly
- Comparing information across websites
- Finding specific types of content (articles, documentation)
- User wants to see original sources

**Command format**:
```bash
python scripts/search.py '["query1", "query2"]' --max-results 10
```

**Tips**:
- Use multiple queries in parallel for related searches
- Default max-results=10 balances token cost vs completeness
- Queries are keyword-focused: "quantum computing 2025" not "tell me about quantum computing in 2025"

### Use Summarizer (`scripts/summarize.py`)

**Cost**: $0.03 per 1K tokens (max $0.30)

**When to use**:
- User provides a specific URL to summarize
- Content is long-form (articles, research papers, videos)
- Translation needed (supports 30+ languages)
- User wants key takeaways from lengthy content

**Command format**:
```bash
python scripts/summarize.py "https://example.com/article" --summary-type takeaway
python scripts/summarize.py "https://youtube.com/watch?v=xxx" --target-language ES
```

**Options**:
- `--summary-type takeaway`: Bulleted key points (default, more token-efficient)
- `--summary-type summary`: Paragraph prose (more detailed)
- `--target-language`: ISO code (EN, ES, FR, etc.) for translation
- `--engine cecil`: Fast, friendly (default)
- `--engine agnes`: Formal, technical

**Supported content**: Web pages, PDFs, Word/PowerPoint docs, audio, YouTube videos

### Use Enrichment (`scripts/enrich.py`)

**Cost**: $0.002 per search (12x cheaper than main search!)

**When to use**:
- Looking for indie/personal blogs
- Finding non-commercial "small web" content
- Alternative news sources
- Discovering niche communities or publications
- User explicitly mentions wanting indie/alternative sources

**Command format**:
```bash
python scripts/enrich.py '["indie web", "personal blogs"]' --type web
python scripts/enrich.py '["alternative news"]' --type news
```

**Options**:
- `--type web`: Small web content (default)
- `--type news`: Alternative news sources

## Cost Optimization Strategy

Follow these guidelines to minimize API costs:

1. **FastGPT first for questions**: If the user asks a question, default to FastGPT unless they specifically need multiple sources
2. **Batch queries**: Use multiple queries in a single call to Search/Enrichment rather than separate calls
3. **Leverage cache**: Identical queries are free on repeat - don't reformulate unnecessarily
4. **Choose takeaway summaries**: Default to `--summary-type takeaway` for token efficiency
5. **Use Enrichment when appropriate**: 12x cheaper than main search for indie content

## Configuration

This skill requires a Kagi API key. Set it as an environment variable:

```bash
export KAGI_API_KEY="your-api-key-here"
```

Get your API key from: https://kagi.com/settings/billing_api

**Important**:
- Never hardcode or expose the API key in prompts
- The skill reads credentials from the environment only
- All scripts will fail gracefully if the key is missing

## Error Handling

The scripts return simple error messages. Interpret and guide the user as follows:

### "KAGI_API_KEY environment variable not set"
- User hasn't configured their API key
- Guide them to: `export KAGI_API_KEY='their-key'`
- Link to: https://kagi.com/settings/billing_api

### "Invalid API key or access not granted"
- API key is incorrect or expired
- For Search API: May need closed beta access - email support@kagi.com
- FastGPT, Summarizer, Enrichment are publicly available

### "Rate limit exceeded"
- User is making requests too quickly
- Wait a moment and retry
- This is rare with normal usage

### "Request failed after 3 attempts"
- Likely Kagi server issue or network problem
- Suggest user try again in a few moments
- Check Kagi status if persistent: https://status.kagi.com

### "Insufficient credits" (if Kagi returns this)
- User's API balance is empty
- Direct them to add credits: https://kagi.com/settings/billing_api

## Query Formulation Best Practices

Craft effective search queries:

**Good queries** (keyword-focused):
- "quantum computing breakthroughs 2025"
- "python async best practices"
- "climate change latest research"

**Poor queries** (too conversational):
- "can you tell me about quantum computing?"
- "I want to learn about python"
- "what's new with climate change?"

**Tips**:
- Include year for recent topics: "AI regulation 2025"
- Use specific terms: "TypeScript generics" not "typescript typing"
- Combine concepts: "kubernetes security hardening"
- For comparisons: "React vs Vue performance 2025"

## Response Formatting

The scripts output markdown-formatted results optimized for token efficiency:

**Search results** (~500-800 tokens for 10 results):
```
1. **Article Title**
   https://example.com/article
   Article snippet truncated to 200 characters...

2. **Another Result**
   ...

### Related Searches
- related topic 1
- related topic 2
```

**FastGPT answers** (~300-500 tokens):
```
## Answer

[AI-generated answer with web grounding]

### Sources
1. [Source Title](URL)
2. [Source Title](URL)

*Generated using 1,234 tokens*
```

**Summaries** (~400-600 tokens):
```
## Summary

- Key point 1
- Key point 2
- Key point 3
```

**Enrichment results** (~400-600 tokens):
```
## Indie Web / Small Web Results

1. **Blog Post Title**
   https://personal-blog.com/post
   Snippet...
```

## Common Usage Patterns

### Pattern 1: Current Events Research
User asks: "What are the latest developments in AI regulation?"

**Approach**:
1. Use Search API with focused query
2. Include year for recency
3. Request multiple results for perspective

```bash
python scripts/search.py '["AI regulation 2025", "AI policy developments"]' --max-results 10
```

### Pattern 2: Quick Factual Answer
User asks: "What is the difference between REST and GraphQL?"

**Approach**:
1. Use FastGPT for cost efficiency
2. Get answer with citations

```bash
python scripts/fastgpt.py "What is the difference between REST and GraphQL?"
```

### Pattern 3: Article Summary
User provides: "Can you summarize this article? [URL]"

**Approach**:
1. Use Summarizer with takeaway format
2. Efficient token usage with bullet points

```bash
python scripts/summarize.py "https://example.com/long-article" --summary-type takeaway
```

### Pattern 4: Finding Indie Content
User asks: "Find some indie blogs about minimalism"

**Approach**:
1. Use Enrichment API for cost efficiency
2. Target small web sources

```bash
python scripts/enrich.py '["minimalism blogs", "simple living"]' --type web
```

### Pattern 5: Multi-Source Research
User asks: "Compare different perspectives on remote work trends"

**Approach**:
1. Use Search with multiple related queries
2. Get diverse sources in one call

```bash
python scripts/search.py '["remote work trends 2025", "hybrid work future", "return to office debate"]'
```

### Pattern 6: Video/Podcast Summary
User provides: "Summarize this YouTube video"

**Approach**:
1. Summarizer handles videos automatically
2. Can translate if needed

```bash
python scripts/summarize.py "https://youtube.com/watch?v=xxx" --summary-type takeaway
```

## Caching Behavior

The skill implements session-scoped caching in `/tmp/kagi-skill-cache/`:

- **Automatic**: All results cached on first call
- **Session-scoped**: Cache cleared on system reboot
- **Keyed by query + endpoint**: Same query to different APIs cached separately
- **Free on hit**: Second call with identical query returns instantly
- **No TTL**: Fresh cache every boot session

**Kagi server-side cache**:
- Identical queries/URLs cached on Kagi's servers
- Cached responses are FREE (no API charges)
- TTL managed by Kagi

## Token Efficiency Comparison

This skill achieves 74%+ token savings vs the Kagi MCP server:

| Scenario | MCP Server | Kagi Skill | Savings |
|----------|-----------|-----------|---------|
| 20-message conversation, 2 searches | ~16,000 tokens | ~4,200 tokens | 74% |
| Startup cost | ~800 tokens | ~100 tokens | 88% |
| Search results (10 items) | ~3,000 tokens | ~600 tokens | 80% |
| FastGPT answer | ~800 tokens | ~400 tokens | 50% |

**How**:
- Progressive disclosure: Only metadata loads until invoked
- Script-based filtering: Results truncated outside context window
- Markdown output: No JSON structural overhead
- Smart defaults: Fewer tokens per result

## Privacy Notes

For sensitive searches, Kagi supports `cache: false` to prevent data retention. This skill defaults to caching enabled for performance. To disable:

- Modify scripts to add `cache=false` to API params
- Note: This prevents both Kagi server cache and local cache
- All cached queries are free; uncached queries always cost

## License

MIT License - See LICENSE file

## Support

- Kagi API Documentation: https://help.kagi.com/kagi/api/overview.html
- Issues: Report to skill maintainer
- Kagi Support: support@kagi.com