search-router

Choose the right search tool for each query type

422 stars

byvibeeval

View on GitHub Installation ↓

Best use case

search-router is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Choose the right search tool for each query type

Teams using search-router should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/search-router/SKILL.md --create-dirs "https://raw.githubusercontent.com/vibeeval/vibecosystem/main/skills/search-router/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/search-router/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How search-router Compares

Feature / Agent	search-router	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Choose the right search tool for each query type

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# Search Tool Router

Use the most token-efficient search tool for each query type.

## When to Use

- Searching for code patterns
- Finding where something is implemented
- Looking for specific identifiers
- Understanding how code works

## Decision Tree

```
Query Type?
├── CODE EXPLORATION (symbols, call chains, data flow)
│   → TLDR Search - 95% token savings
│   DEFAULT FOR ALL CODE SEARCH - use instead of Grep
│   Examples: "spawn_agent", "DataPoller", "redis usage"
│   Command: tldr search "query" .
│
├── STRUCTURAL (AST patterns)
│   → AST-grep (/ast-grep-find) - ~50 tokens output
│   Examples: "def foo", "class Bar", "import X", "@decorator"
│
├── SEMANTIC (conceptual questions)
│   → TLDR Semantic - 5-layer embeddings (P6)
│   Examples: "how does auth work", "find error handling patterns"
│   Command: tldr semantic search "query"
│
├── LITERAL (exact text, regex)
│   → Grep tool - LAST RESORT
│   Only when TLDR/AST-grep don't apply
│   Examples: error messages, config values, non-code text
│
└── FULL CONTEXT (need complete understanding)
    → Read tool - 1500+ tokens
    Last resort after finding the right file
```

## Token Efficiency Comparison

| Tool | Output Size | Best For |
|------|-------------|----------|
| **TLDR** | **~50-500** | **DEFAULT: Code symbols, call graphs, data flow** |
| **TLDR Semantic** | **~100-300** | **Conceptual queries (P6, embedding-based)** |
| AST-grep | ~50 tokens | Function/class definitions, imports, decorators |
| Grep | ~200-2000 | LAST RESORT: Non-code text, regex |
| Read | ~1500+ | Full understanding after finding the file |

## Examples

```bash
# CODE EXPLORATION → TLDR (DEFAULT)
tldr search "spawn_agent" .
tldr search "redis" . --layer call_graph

# STRUCTURAL → AST-grep
/ast-grep-find "async def $FUNC($$$):" --lang python

# SEMANTIC → TLDR Semantic
tldr semantic search "how does authentication work"

# LITERAL → Grep (LAST RESORT - prefer TLDR)
Grep pattern="check_evocation" path=opc/scripts

# FULL CONTEXT → Read (after finding file)
Read file_path=opc/scripts/z3_erotetic.py
```

## Optimal Flow

```
1. AST-grep: "Find async functions" → 3 file:line matches
2. Read: Top match only → Full understanding
3. Skip: 4 irrelevant files → 6000 tokens saved
```

## Related Skills

- `/tldr-search` - **DEFAULT** - Code exploration with 95% token savings
- `/ast-grep-find` - Structural code search
- `/morph-search` - Fast text search