smart-explore

Overview of smart-explore skill

What smart-explore does

The smart-explore skill is a codebase exploration workflow built around structural search, not raw file reading. Its main job is to help an agent understand a repository faster by using AST-based tools such as smart_search, smart_outline, and smart_unfold before loading full files. If you are evaluating smart-explore for code navigation, architecture discovery, or targeted debugging, the key promise is simple: map the code first, then read only the parts that matter.

Who should install smart-explore

smart-explore is best for users who regularly ask an AI to inspect unfamiliar codebases and want fewer wasted tokens and less random file surfing. It is especially useful for:

• code review and change impact analysis
• onboarding into large repositories
• finding the real implementation behind a feature name
• locating symbols, handlers, services, and call sites quickly
• reducing noisy Read/Grep/Glob exploration loops

The strongest fit is smart-explore for Code Review, where understanding structure and symbol boundaries matters more than reading every line.

The real job-to-be-done

Most repository exploration fails because the agent starts reading files too early. smart-explore changes that behavior. Instead of “open files until something looks relevant,” it pushes a workflow of:

1. search for matching symbols across a directory
2. outline the relevant file structure
3. unfold only the symbol you actually need

That makes the smart-explore skill more than a search shortcut; it is a decision rule for when not to read full files.

What makes smart-explore different from a generic prompt

A normal prompt can tell a model to “be efficient,” but smart-explore gives a specific tool order and a clear replacement for default repository browsing habits. The differentiator is not extra documentation depth; it is the explicit override: use smart_search/smart_outline/smart_unfold as the primary exploration path instead of Read, Grep, Glob, or ad hoc file discovery.

What matters before you install

The biggest adoption question is not “is the idea good?” but “do I have the right tool environment?” smart-explore only makes sense if your setup exposes the matching MCP tools. The skill itself is lightweight and instruction-driven; the value depends on whether your agent can actually call the structural exploration tools it references.

How to Use smart-explore skill

Confirm the tool dependency first

Before trying any smart-explore install flow, verify that your environment supports these MCP tools:

• smart_search
• smart_outline
• smart_unfold

This skill does not replace those tools and does not bundle them. It changes the agent's exploration strategy. If those tool names are unavailable in your client, smart-explore usage will be limited to ideas rather than execution.

Install context and where the skill lives

The repository path for this skill is:

plugin/skills/smart-explore

The page-level install pattern commonly used for this repo family is:

npx skills add thedotmack/claude-mem --skill smart-explore

Because the upstream SKILL.md does not include its own install command, treat the command above as the practical install entry point for this skill collection, then verify your local skill loader and MCP configuration.

Read this file first

Start with:

• plugin/skills/smart-explore/SKILL.md

There are no extra README.md, metadata.json, rules/, or resources/ files supporting this skill, so nearly all of the usable guidance is concentrated in that single file. That is helpful for quick evaluation, but it also means you should not expect deeper examples or edge-case docs elsewhere.

The core smart-explore usage pattern

The skill is built around a 3-layer workflow:

1. smart_search to discover relevant files and symbols
2. smart_outline to inspect a file's structure without loading the whole file
3. smart_unfold to fetch the exact symbol you need in full

This is the practical heart of the smart-explore guide. If you skip step 1 and start reading whole files, you are not really using the skill as intended.

Your first prompt should be goal-plus-scope

Weak prompt:

“Find the bug in auth.”

Stronger prompt:

“Use smart-explore on ./src to find where token refresh is implemented. Start with smart_search for refresh token, outline the top 2 matching files, then unfold the main refresh handler and summarize control flow.”

Why this is better:

• it tells the agent to invoke the skill behavior explicitly
• it defines search terms
• it narrows the path
• it asks for structure before full code

How to turn a rough goal into a good smart-explore prompt

For strong smart-explore usage, include these inputs:

• the topic or feature name
• the search root path
• the preferred number of results
• whether you want discovery, review, tracing, or extraction
• which symbols should be unfolded if found

Template:

“Use smart-explore in <path>. Search for <concept>, return up to <n> ranked symbols, outline the most relevant files, then unfold the symbol most likely responsible for <job-to-be-done>. Avoid reading full files unless the outline is insufficient.”

Best workflow for smart-explore for Code Review

For code review, do not ask the agent to “review the whole diff” first if the codebase context is unclear. A better sequence is:

1. search for the feature, class, endpoint, or function name touched by the change
2. outline the touched files to understand surrounding structure
3. unfold only changed or adjacent symbols
4. compare the changed logic against nearby interfaces, validators, or callers
5. read full files only when symbol-level context is insufficient

This lowers noise and helps the reviewer understand what the changed code is attached to.

When to use smart_search first

Use smart_search when you know a concept but not the exact file. Good queries include:

• feature names
• endpoint names
• error messages
• domain terms
• method names
• state transitions

The skill explicitly advises against using Grep, Glob, Read, or find for initial discovery when structural search is available. The reason is decision quality: ranked symbol matches are usually more actionable than raw text hits.

When to use smart_outline next

Use smart_outline when you have found a likely file but do not yet want implementation details. This is the right move when you need to know:

• what classes or functions exist in the file
• whether the target symbol is really there
• where top-level structure begins and ends
• whether a file is worth reading in full

This step is especially useful in large files where full reads waste tokens.

When to use smart_unfold

Use smart_unfold after you have identified the symbol that likely contains the logic you need. This is the highest-signal way to inspect:

• one handler
• one service method
• one resolver
• one reducer
• one utility function

If you unfold too early, you may miss the better symbol. If you unfold too late, you waste time outlining files that are already obviously relevant.

Practical prompt examples that improve output quality

Example 1:

“Use smart-explore on ./src to locate the shutdown sequence. Search shutdown, outline the top relevant file, then unfold the main shutdown function and identify its dependencies.”

Example 2:

“Use smart-explore for Code Review on ./app. Search for rate limit, outline matching middleware files, then unfold the enforcement symbol and summarize request flow and likely edge cases.”

Example 3:

“Use smart-explore to find where email verification is triggered. Search verify email, rank up to 10 results, outline the top 3 files, and unfold the symbol that sends or schedules the verification.”

smart-explore skill FAQ

Is smart-explore worth installing if I already use good prompts

Yes, if your environment supports the tools it expects. The benefit of smart-explore is not just better wording; it is a stronger exploration policy. It makes the agent prefer structural discovery over file-by-file wandering, which is often the real source of wasted time.

Is smart-explore beginner-friendly

Moderately. The idea is simple, but beginners can get blocked if they do not understand the difference between symbol discovery and file reading, or if they install the skill without the required MCP tool support. If you are new, start with one narrow feature search rather than a whole-repo task.

When should I not use smart-explore

Skip smart-explore when:

• your environment lacks smart_search, smart_outline, and smart_unfold
• you already know the exact tiny file and symbol to inspect
• the repository is so small that full-file reading is cheaper than structural setup
• your task is prose-heavy rather than code-structure-heavy

How is smart-explore different from ordinary Grep or Read

Grep gives text matches. Read gives raw file content. smart-explore is designed to find and inspect code structure at the symbol level first. That usually means better ranking, clearer boundaries, and fewer unnecessary full-file loads.

Is smart-explore good for large monorepos

Yes, that is one of the strongest fit cases, assuming the backing tools perform well in your setup. The “index first, fetch on demand” mindset is most useful when a repo is too large for naive browsing.

Can I use smart-explore for Code Review only

Yes. In fact, code review is one of the clearest use cases because reviewers often need to understand nearby symbols and call structure without rereading every touched file in full. smart-explore for Code Review is a strong fit when the review question is “what is this change connected to?”

How to Improve smart-explore skill

Give smarter search queries, not broader ones

The quality of smart-explore output depends heavily on the first query. Better queries usually combine a domain term and an action, such as:

• refresh token
• session revoke
• password reset
• shutdown
• rate limit

Overly broad queries like auth or user often return noisy symbol sets and weaken the rest of the workflow.

Always include a path scope

One of the easiest ways to improve smart-explore usage is to specify the search root, such as ./src, ./app, or a package directory. Without scope, results may be noisier and slower, especially in larger repos.

Ask for ranking and a decision step

Do not just ask the agent to search. Ask it to choose. Example:

“Search for invoice export in ./services, rank the top 8 symbols, explain which 2 are most likely relevant, then outline those files before unfolding one symbol.”

This forces a selection stage and reduces blind tool churn.

Use outlines to avoid premature full reads

A common failure mode is falling back to full-file reading after the first search result. To get better value from smart-explore, explicitly tell the agent:

“Do not read full files unless the outline does not provide enough context.”

That keeps the workflow aligned with the skill's main advantage.

Improve smart-explore for Code Review with change-aware prompts

For code review, combine the changed area with the architectural question. Example:

“Use smart-explore on ./src/payments to review the new refund path. Search refund, outline affected files, unfold the entry-point symbol and the main downstream processor, then check for validation, idempotency, and error handling gaps.”

This is better than “review this code” because it directs the structural exploration toward review risk.

Watch for the main failure modes

The most likely problems are:

• missing MCP tool support
• search terms that are too vague
• skipping straight from search to conclusions
• unfolding the wrong symbol because the file was never outlined
• using the skill on tiny repos where its structure-first method adds overhead

These are fixable, but they matter more than polish in the SKILL.md.

Iterate after the first result instead of restarting

Good smart-explore guide practice is iterative narrowing. After the first run:

• refine the query with a more specific term
• narrow the path
• increase or decrease max_results
• outline a second candidate file
• unfold a neighboring symbol, not just the first match

That usually gives better results than abandoning the workflow and switching to random file reads.

What would make the smart-explore skill itself stronger

The current smart-explore documentation is usable but thin. The skill would be easier to adopt with:

• one explicit install section
• one beginner example from search to unfold
• one code review example
• one short “when not to use this” section
• one note clarifying MCP/tool prerequisites up front

Those additions would reduce pre-install guesswork and make the smart-explore skill easier to trigger correctly on the first try.