claude-mem/plugin/skills/smart-explore/SKILL.md

name, description

name	description
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.

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.

Your Next Tool Call

This skill only loads instructions. You must call the MCP tools yourself. Your next action should be one of:

smart_search(query="<topic>", path="./src")    -- discover files + symbols across a directory
smart_outline(file_path="<file>")              -- structural skeleton of one file
smart_unfold(file_path="<file>", symbol_name="<name>")  -- full source of one symbol

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

smart_search(query="shutdown", path="./src", max_results=15)

Returns: Ranked symbols with signatures, line numbers, match reasons, plus folded file views (~2-6k tokens)

-- Matching Symbols --
  function performGracefulShutdown (services/infrastructure/GracefulShutdown.ts:56)
  function httpShutdown (services/infrastructure/HealthMonitor.ts:92)
  method WorkerService.shutdown (services/worker-service.ts:846)

-- Folded File Views --
  services/infrastructure/GracefulShutdown.ts (7 symbols)
  services/worker-service.ts (12 symbols)

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

smart_outline(file_path="services/worker-service.ts")

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:

smart_unfold(file_path="services/worker-service.ts", symbol_name="shutdown")

Returns: Full source code of the specified symbol including JSDoc, decorators, and complete implementation (~1-7k tokens depending on symbol size)

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")

For code files over ~100 lines, prefer smart_outline + smart_unfold over Read.

Workflow Examples

Discover how a feature works (cross-cutting):

1. smart_search(query="shutdown", path="./src")
   -> 14 symbols across 7 files, full picture in one call
2. smart_unfold(file_path="services/infrastructure/GracefulShutdown.ts", symbol_name="performGracefulShutdown")
   -> See the core implementation

Navigate a large file:

1. smart_outline(file_path="services/worker-service.ts")
   -> 1,466 tokens: 12 functions, WorkerService class with 24 members
2. smart_unfold(file_path="services/worker-service.ts", symbol_name="startSessionProcessor")
   -> 1,610 tokens: the specific method you need
Total: ~3,076 tokens vs ~12,000 to Read the full file

Write documentation about code (hybrid workflow):

1. smart_search(query="feature name", path="./src")    -- discover all relevant files and symbols
2. smart_outline on key files                           -- understand structure
3. smart_unfold on important functions                  -- get implementation details
4. Read on small config/markdown/plan files             -- get non-code context

Use smart_* tools for code exploration, Read for non-code files. Mix freely.

Exploration then precision:

1. smart_search(query="session", path="./src", max_results=10)
   -> 10 ranked symbols: SessionMetadata, SessionQueueProcessor, SessionSummary...
2. Pick the relevant one, unfold it

Token Economics

Approach	Tokens	Use Case
smart_outline	~1,500	"What's in this file?"
smart_unfold	~1,600	"Show me this function"
smart_search	~2,000-6,000	"How does X work?"
Read (full file)	~12,000+	When you truly need everything
Explore agent	~20,000-40,000	Same as smart_search, 6-12x more expensive

8x savings on file understanding (outline + unfold vs Read). 6-12x savings on exploration vs Explore agent.