What is Search Tool Router?

A routing guide that directs your query to the most token-efficient search tool for the given type of question.

When should I use TLDR instead of Grep?

Use TLDR for code exploration to maximize token savings and signal; Grep is a last resort for non-code or literal text.

How do I get full context after an initial search?

After locating a promising file with AST-grep or TLDR, use Read to load the file and gain full context for thorough understanding.

search-router

npx machina-cli add skill parcadei/Continuous-Claude-v3/search-router --openclaw

Files (1)

SKILL.md

2.6 KB

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

# 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

Source

git clone https://github.com/parcadei/Continuous-Claude-v3/blob/main/.claude/skills/search-router/SKILL.mdView on GitHub

Overview

Search Tool Router directs queries to the most token-efficient tool for code search, structural patterns, semantic questions, literals, or full-context reading. By routing to TLDR, AST-grep, TLDR Semantic, Grep, or Read, it saves tokens while keeping results precise and actionable.

How This Skill Works

The router evaluates the query against a decision tree and selects the optimal tool: TLDR for code exploration, AST-grep for structural patterns, TLDR Semantic for conceptual questions, Grep as a last resort for literal text, and Read for full-context understanding. It then guides you along the recommended flow to efficiently retrieve results.

When to Use It

Searching for code patterns
Finding where something is implemented
Looking for specific identifiers
Understanding how code works
Need full context after locating a file

Quick Start

Step 1: Determine the query type (code exploration, structural, semantic, literal, or full context)
Step 2: Run the recommended command from the decision tree (TLDR, AST-grep, TLDR Semantic, Grep, or Read)
Step 3: If needed, use Read to load the full file for deeper understanding

Best Practices

Use AST-grep for structural searches like function/class definitions and imports
Prefer TLDR for code exploration to maximize token savings
Use TLDR Semantic for conceptual or design-level questions
Reserve Grep for literal text when code search isn’t applicable
Move to Read only after you’ve pinpointed the relevant file

Example Use Cases

tldr search spawn_agent
tldr search redis . --layer call_graph
/ast-grep-find async def $FUNC($$$): --lang python
tldr semantic search how does authentication work
Grep pattern=check_evocation path=opc/scripts

Frequently Asked Questions

Add this skill to your agents