Smart Explore

Smart Explore:

Intelligent Codebase Exploration with MCP Tools

What Is This

Smart Explore is a development skill designed for the Happycapy Skills platform, focusing on token-optimized, structural code exploration. By leveraging tree-sitter Abstract Syntax Tree (AST) parsing, Smart Explore provides a more intelligent and efficient way to navigate and understand large codebases. Unlike traditional file reading or basic text searches, this skill enables you to index an entire codebase structurally, allowing you to discover files, understand code structure, and isolate functions or classes without reading full file contents. While Smart Explore is active, it overrides your default exploration tools, encouraging a map-first approach to code comprehension.

Why Use It

Exploring unfamiliar or complex codebases can be time-consuming and inefficient if you rely solely on reading files or running basic grep and glob operations. These traditional methods often consume unnecessary resources and tokens, especially in AI-driven environments. Smart Explore addresses these challenges by:

• Providing a bird’s-eye structural overview before delving into implementation details.
• Reducing token consumption by only loading what is necessary.
• Leveraging AST parsing for precise symbol and function discovery.
• Streamlining code navigation workflows, particularly in large projects with deep directory trees.
• Replacing inefficient cycles of file discovery and reading with a single, powerful search and outline strategy.

How to Use It

When Smart Explore is enabled, your codebase exploration workflow changes fundamentally. Instead of using basic tools like Read, Grep, or Glob, you interact with a set of specialized MCP tools:

Core MCP Tool Calls

1. smart_search

   • Discover files and symbols matching a specific topic or keyword across a directory.
   • Example:
     python

     smart_search(query="authentication", path="./src")

   • This command walks through the specified directory, parses all code files, and returns a ranked list of relevant symbols.

2. smart_outline

   • Retrieve the structural skeleton (outline) of a single file, such as classes, functions, and key definitions.
   • Example:
     python

     smart_outline(file_path="./src/user/session.py")

   • This gives you a concise map of a file's structure without reading its entire content.

3. smart_unfold

   • Extract the full source code of a specific symbol (function, class, etc.) within a file.
   • Example:
     python

     smart_unfold(file_path="./src/user/session.py", symbol_name="UserSessionManager")

   • This allows targeted inspection of implementation details for a specific symbol.

Important: Do NOT use Grep, Glob, Read, or manual file discovery methods when Smart Explore is active. The smart_search command is designed to replace the entire file discovery and reading cycle with a single, efficient operation.

When to Use It

Smart Explore is best suited for scenarios where you need to:

• Quickly understand the architecture or layout of a new or unfamiliar codebase.
• Locate all occurrences of a symbol, function, or class across nested directories.
• Explore code structure efficiently without loading unnecessary code.
• Minimize token usage by only fetching details on demand.
• Prepare for tasks such as refactoring, debugging, or onboarding to a new project.

This skill is particularly valuable for large, modular projects where reading every file would be impractical and costly.

Important Notes

• Index First, Fetch on Demand: Always begin with an index (using smart_search or smart_outline) before diving into full file reads. This philosophy prevents unnecessary data loading and keeps your exploration focused and efficient.
• Skill Overrides Default Tools: While Smart Explore is enabled, avoid using Read, Grep, Glob, or similar commands for exploration. The specialized MCP tools provide all necessary discovery and navigation functionality.
• No Automatic Tool Calls: Activating Smart Explore loads only the skill’s instructions. You are responsible for invoking the appropriate MCP tools as your next action.
• Optimization for Token Usage: The skill is specifically designed to minimize token consumption in AI-driven workflows, making it ideal for chat-based or automated code review environments.
• Structural, Not Content-Heavy: Smart Explore is optimized for structural understanding. Request full symbol code only when implementation details are required.

By adopting Smart Explore on the Happycapy platform, you can dramatically improve your efficiency in code navigation, symbol discovery, and architectural comprehension, all while reducing unnecessary resource usage. Use this skill whenever deep, intelligent exploration of a codebase is needed.