search-hierarchy — Claude Code skill for code search
The search-hierarchy skill picks a search tool based on whether a question concerns code structure, meaning, or an exact identifier. It helps locate a relevant file before reading it.
MIT ★ 3,951 updated 2026-01-26
npx skills add parcadei/Continuous-Claude-v3 --skill search-hierarchy -a claude-codeWhat search-hierarchy does
search-hierarchy routes code searches to AST-grep, LEANN, Grep, or Read. AST-grep handles structural queries such as locating function definitions and imports. LEANN is for questions about how a system works; Grep finds exact names and regex matches. Read comes after search, when a file needs closer inspection.
The grep-to-leann.sh hook classifies queries. It blocks Grep for structural and conceptual searches and suggests AST-grep or LEANN; literal patterns can pass through to Grep. That means a broad question about code behaviour won't go straight to Grep. Install the skill in Claude Code with npx skills add parcadei/Continuous-Claude-v3 --skill search-hierarchy -a claude-code.
What it helps with
- Locate function and class definitions by code structure
- Trace how authentication works
- Find an exact identifier or regex match
- Read a relevant file after locating it
Example prompts for the agent
- Find async function definitions in this project.
- Explain how authentication works and locate the relevant file.
- Find exact matches for
check_evocationinopc/scripts.
How to install search-hierarchy
1Skills CLI (Vercel)
npx skills add parcadei/Continuous-Claude-v3 --skill search-hierarchy -a claude-code2Manually: put the files in place
~/.claude/skills/search-hierarchy/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/search-hierarchy/
1Skills CLI (Vercel)
npx skills add parcadei/Continuous-Claude-v3 --skill search-hierarchy -a codex2Manually: put the files in place
.agents/skills/search-hierarchy/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add parcadei/Continuous-Claude-v3 --skill search-hierarchy -a cursor2Manually: put the files in place
.cursor/skills/search-hierarchy/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install parcadei/Continuous-Claude-v3 .claude/skills/search-hierarchy2Manually: put the files in place
.github/skills/search-hierarchy/SKILL.md1Skills CLI (Vercel)
npx skills add parcadei/Continuous-Claude-v3 --skill search-hierarchy -a gemini-cli2Platform CLI
gemini skills install https://github.com/parcadei/Continuous-Claude-v3 --path .claude/skills/search-hierarchyManually: put the files in place
.devin/skills/search-hierarchy/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about search-hierarchy
How do I install search-hierarchy in Claude Code?
Run npx skills add parcadei/Continuous-Claude-v3 --skill search-hierarchy -a claude-code. The skill file is at ~/.claude/skills/search-hierarchy/SKILL.md.
What does search-hierarchy do?
It routes structural searches to AST-grep, conceptual questions to LEANN, and exact matches to Grep. Read is reserved for inspecting a file found through search.
What does the search-hierarchy hook enforce?
The grep-to-leann.sh hook classifies queries and blocks Grep for structural or conceptual searches, suggesting AST-grep or LEANN instead.
Source text
SKILL.md · MIT
---
name: search-hierarchy
description: Search Tool Hierarchy
user-invocable: false
---
# 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:
1. Detects query type (structural/semantic/literal)
2. Blocks and suggests AST-grep for structural queries
3. Blocks and suggests LEANN for semantic queries
4. 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
```bash
# 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
```
© parcadei · MIT · parcadei/Continuous-Claude-v3