Token-optimized structural code search using tree-sitter AST parsing. Use instead of reading full files when you need to understand code structure, find functions, or explore a codebase efficiently.

Smart Explore Structural code exploration using AST parsing. This skill overrides your default exploration behavior. While this skill is active, use smart search/smart outline/smart unfold as your primary tools instead of Read, Grep, and Glob. Core principle: Index first, fetch on demand. Give yourself a map of the code before loading implementation details. The question before every file read should be: "do I need to see all of this, or can I get a structural overview first?" The answer is almost always: get the map. Your Next Tool Call This skill only loads instructions. You must call the MCP tools yourself. Your next action should be one of: Do NOT run Grep, Glob, Read, or find to discover files first. smart search walks directories, parses all code files, and returns ranked symbols in one call. It replaces the Glob → Grep → Read discovery cycle. 3 Layer Workflow Step 1: Search Discover Files and Symbols Returns: Ranked symbols with signatures, line numbers, match reasons, plus folded file views (~2 6k tokens) This is your discovery tool. It finds relevant files AND shows their structure. No Glob/find pre scan needed. Parameters: query (string, required) What to search for (function name, concept, class name) path (string) Root directory to search (defaults to cwd) max results (number) Max matching symbols, default 20, max 50 file pattern (string, optional) Filter to specific files/paths Step 2: Outline Get File Structure Returns: Complete structural skeleton all functions, classes, methods, properties, imports (~1 2k tokens per file) Skip this step when Step 1's folded file views already provide enough structure. Most useful for files not covered by the search results. Parameters: file path (string, required) Path to the file Step 3: Unfold See Implementation Review symbols from Steps 1 2. Pick the ones you need. Unfold only those: Returns: Full source code of the specified symbol including JSDoc, decorators, and complete implementation (~400 2,100 tokens depending on symbol size). AST node boundaries guarantee completeness regardless of symbol size — unlike Read + agent summarization, which may truncate long methods. Parameters: file path (string, required) Path to the file (as returned by search/outline) symbol name (string, required) Name of the function/class/method to expand When to Use Standard Tools Instead Use these only when smart tools are the wrong fit: Grep: Exact string/regex search ("find all TODO comments", "where is ensureWorkerStarted defined?") Read: Small files under ~100 lines, non code files (JSON, markdown, config) Glob: File path patterns ("find all test files") Explore agent: When you need synthesized understanding across 6+ files, architecture narratives, or answers to open ended questions like "how does this entire system work end to end?" Smart explore is a scalpel — it answers "where is this?" and "show me that." It doesn't synthesize cross file data flows, design decisions, or edge cases across an entire feature. For code files over ~100 lines, prefer smart outline + smart unfold over Read. Workflow Examples Discover how a feature works (cross cutting): Navigate a large file: Write documentation about code (hybrid workflow): Use smart tools for code exploration, Read for non code files. Mix freely. Exploration then precision: Token Economics Approach Tokens Use Case smart outline ~1,000 2,000 "What's in this file?" smart unfold ~400 2,100 "Show me this function" smart search ~2,000 6,000 "Find all X across the codebase" search + unfold ~3,000 8,000 End to end: find and read (the primary workflow) Read (full file) ~12,000+ When you truly need everything Explore agent ~39,000 59,000 Cross file synthesis with narrative 4 8x savings on file understanding (outline + unfold vs Read). 11 18x savings on codebase exploration vs Explore agent. The narrower the query, the wider the gap — a 27 line function costs 55x less to read via unfold than via an Explore agent, because the agent still reads the entire file. Language Support Smart explore uses tree sitter AST parsing for structural analysis. For file contents outside its language support, use a text search tool such as rg . Bundled Languages Language Extensions JavaScript .js , .mjs , .cjs TypeScript .ts TSX / JSX .tsx , .jsx Python .py , .pyw Go .go Rust .rs Ruby .rb Java .java C .c , .h C++ .cpp , .cc , .cxx , .hpp , .hh Files with unrecognized extensions do not produce structured symbols for smart outline or smart unfold . smart search is not a general file content search: its extension filter can exclude unsupported files, and files without symbols can match only by path. Use rg or another text search tool to search their contents. Additional languages Custom tree sitter grammars cannot currently be registered through .claude mem.json . Installing a grammar in a project's node modules does not enable structural parsing for its extensions. Support must be added to the shipped language map, grammar packages and symbol queries before smart outline and smart unfold can use it. Markdown Special Support Markdown files ( .md , .mdx ) receive special handling beyond the generic plain text fallback: smart outline — extracts headings ( , , ) as the symbol tree. Use it to navigate long documents without reading the full file. smart search — searches within code fences as well as prose, so queries for function names inside blocks work as expected. smart unfold — expands heading sections rather than function bodies; each section up to the next same level heading is returned as a chunk. Frontmatter — YAML frontmatter (lines between leading delimiters) is included in smart outline output under a synthetic frontmatter symbol so metadata like title: and description: is visible without reading the whole file.

smart-explore