Agent skill · research science · thedotmack
smart-explore
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.
Why this skill is useful
Adds domain-specific commands for efficient codebase exploration using AST parsing that the AI wouldn't reliably generate on its own.
What it needs
Requires tree-sitter installed locally. About 5k tokens when loaded. Last updated 2026-08-05. 89,894 stars on the source repository.
What this skill does
Smart Explore Structural code exploration using AST parsing. This skill overrides your default exploration behavior. While this skill is active, use smartsearch/smartoutline/smartunfold 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. smartsearch 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) maxresults (number) -- Max matching symbols, default 20, max 50 filepattern (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: filepath (string, required) -- Path to the file Step 3: Unfold -- See Implementation Review symbols from Steps 1-2. Pick the ones you need. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills thedotmack/smart-explore