search-hierarchy
npx machina-cli add skill parcadei/Continuous-Claude-v3/search-hierarchy --openclawFiles (1)
SKILL.md
2.3 KB
Search Tool Hierarchy
Use the most token-efficient search tool for each query type.
Decision Tree
Query Type?
├── STRUCTURAL (code patterns)
│ → AST-grep (~50 tokens output)
│ Examples: "def foo", "class Bar", "import X", "@decorator"
│
├── SEMANTIC (conceptual questions)
│ → LEANN (~100 tokens if path-only)
│ Examples: "how does auth work", "find error handling patterns"
│
├── LITERAL (exact identifiers)
│ → Grep (variable output)
│ Examples: "TemporalMemory", "check_evocation", regex patterns
│
└── FULL CONTEXT (need complete understanding)
→ Read (1500+ tokens)
Last resort after finding the right file
Token Efficiency Comparison
| Tool | Output Size | Best For |
|---|---|---|
| AST-grep | ~50 tokens | Function/class definitions, imports, decorators |
| LEANN | ~100 tokens | Conceptual questions, architecture, patterns |
| Grep | ~200-2000 | Exact identifiers, regex, file paths |
| Read | ~1500+ | Full understanding after finding the file |
Hook Enforcement
The grep-to-leann.sh hook automatically:
- Detects query type (structural/semantic/literal)
- Blocks and suggests AST-grep for structural queries
- Blocks and suggests LEANN for semantic queries
- Allows literal patterns through to Grep
DO
- Start with AST-grep for code structure questions
- Use LEANN for "how does X work" questions
- Use Grep only for exact identifier matches
- Read files only after finding them via search
DON'T
- Use Grep for conceptual questions (returns nothing)
- Read files before knowing which ones are relevant
- Use Read when AST-grep would give file:line
- Ignore hook suggestions
Examples
# STRUCTURAL → AST-grep
ast-grep --pattern "async def $FUNC($$$):" --lang python
# SEMANTIC → LEANN
leann search opc-dev "how does authentication work" --top-k 3
# LITERAL → Grep
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
Source
git clone https://github.com/parcadei/Continuous-Claude-v3/blob/main/.claude/skills/search-hierarchy/SKILL.mdView on GitHub Overview
Search Tool Hierarchy guides selecting the most token-efficient search tool for each query type (structural, semantic, literal, full context). It provides a decision tree, a token-efficiency table, and a recommended flow (AST-grep, LEANN, Grep, Read) to minimize tokens while locating relevant code.
How This Skill Works
It classifies the query type and routes to the best tool: structural questions use AST-grep, semantic questions use LEANN, literal questions use Grep, and full-context needs use Read as a last resort. A hook enforces this flow by blocking or suggesting tools based on the query, and you should Read only after finding the right file to maximize efficiency.
When to Use It
- You need to identify a function, class, or import in a codebase (structural).
- You want to understand how a system works conceptually (semantic).
- You require an exact identifier, variable, or regex pattern (literal).
- You must read a file deeply to gain full understanding after narrowing down results (full context).
- You aim to minimize token usage by following the optimal routing flow (token efficiency).
Quick Start
- Step 1: Use AST-grep for structural queries like function/class definitions or imports.
- Step 2: If the question is conceptual, run LEANN on the top results to surface architecture ideas.
- Step 3: For exact identifiers, run Grep; only use Read on the best-matching file after narrowing.
Best Practices
- Start with AST-grep for code structure questions.
- Use LEANN for questions about how something works or architecture.
- Use Grep only for exact identifier matches.
- Read files only after you’ve found relevant files via search.
- Follow hook suggestions to automatically route queries to the right tool.
Example Use Cases
- Structural: Find async function definitions and imports with AST-grep in a Python project.
- Semantic: Ask LEANN how authentication works within the OPC-dev system.
- Literal: Use Grep to locate the exact identifier check_evocation across scripts.
- Full Context: Read the top-matching file after narrowing down via AST-grep to understand behavior.
- Optimal flow: 3-file filter using AST-grep, Read, then skip irrelevant files to save tokens.
Frequently Asked Questions
Add this skill to your agents
