{"id":"smart-explore","name":"smart-explore","summary":"ツリーシッターAST解析を用いたトークン最適化構造符号検索。コード構造を理解したり、関数を探したり、コードベースを効率的に探索したいときは、ファイルを丸ごと読む代わりに使ってください。","body":"# Smart Explore\n\nStructural 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.\n\n**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.\n\n## Your Next Tool Call\n\nThis skill only loads instructions. You must call the MCP tools yourself. Your next action should be one of:\n\n```\nsmart_search(query=\"<topic>\", path=\"./src\")    -- discover files + symbols across a directory\nsmart_outline(file_path=\"<file>\")              -- structural skeleton of one file\nsmart_unfold(file_path=\"<file>\", symbol_name=\"<name>\")  -- full source of one symbol\n```\n\nDo 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.\n\n## 3-Layer Workflow\n\n### Step 1: Search -- Discover Files and Symbols\n\n```\nsmart_search(query=\"shutdown\", path=\"./src\", max_results=15)\n```\n\n**Returns:** Ranked symbols with signatures, line numbers, match reasons, plus folded file views (~2-6k tokens)\n\n```\n-- Matching Symbols --\n  function performGracefulShutdown (services/infrastructure/GracefulShutdown.ts:56)\n  function httpShutdown (services/infrastructure/HealthMonitor.ts:92)\n  method WorkerService.shutdown (services/worker-service.ts:846)\n\n-- Folded File Views --\n  services/infrastructure/GracefulShutdown.ts (7 symbols)\n  services/worker-service.ts (12 symbols)\n```\n\nThis is your discovery tool. It finds relevant files AND shows their structure. No Glob/find pre-scan needed.\n\n**Parameters:**\n\n- `query` (string, required) -- What to search for (function name, concept, class name)\n- `path` (string) -- Root directory to search (defaults to cwd)\n- `max_results` (number) -- Max matching symbols, default 20, max 50\n- `file_pattern` (string, optional) -- Filter to specific files/paths\n\n### Step 2: Outline -- Get File Structure\n\n```\nsmart_outline(file_path=\"services/worker-service.ts\")\n```\n\n**Returns:** Complete structural skeleton -- all functions, classes, methods, properties, imports (~1-2k tokens per file)\n\n**Skip this step** when Step 1's folded file views already provide enough structure. Most useful for files not covered by the search results.\n\n**Parameters:**\n\n- `file_path` (string, required) -- Path to the file\n\n### Step 3: Unfold -- See Implementation\n\nReview symbols from Steps 1-2. Pick the ones you need. Unfold only those:\n\n```\nsmart_unfold(file_path=\"services/worker-service.ts\", symbol_name=\"shutdown\")\n```\n\n**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.\n\n**Parameters:**\n\n- `file_path` (string, required) -- Path to the file (as returned by search/outline)\n- `symbol_name` (string, required) -- Name of the function/class/method to expand\n\n## When to Use Standard Tools Instead\n\nUse these only when smart_* tools are the wrong fit:\n\n- **Grep:** Exact string/regex search (\"find all TODO comments\", \"where is `ensureWorkerStarted` defined?\")\n- **Read:** Small files under ~100 lines, non-code files (JSON, markdown, config)\n- **Glob:** File path patterns (\"find all test files\")\n- **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.\n\nFor code files over ~100 lines, prefer smart_outline + smart_unfold over Read.\n\n## Workflow Examples\n\n**Discover how a feature works (cross-cutting):**\n\n```\n1. smart_search(query=\"shutdown\", path=\"./src\")\n   -> 14 symbols across 7 files, full picture in one call\n2. smart_unfold(file_path=\"services/infrastructure/GracefulShutdown.ts\", symbol_name=\"performGracefulShutdown\")\n   -> See the core implementation\n```\n\n**Navigate a large file:**\n\n```\n1. smart_outline(file_path=\"services/worker-service.ts\")\n   -> 1,466 tokens: 12 functions, WorkerService class with 24 members\n2. smart_unfold(file_path=\"services/worker-service.ts\", symbol_name=\"startSessionProcessor\")\n   -> 1,610 tokens: the specific method you need\nTotal: ~3,076 tokens vs ~12,000 to Read the full file\n```\n\n**Write documentation about code (hybrid workflow):**\n\n```\n1. smart_search(query=\"feature name\", path=\"./src\")    -- discover all relevant files and symbols\n2. smart_outline on key files                           -- understand structure\n3. smart_unfold on important functions                  -- get implementation details\n4. Read on small config/markdown/plan files             -- get non-code context\n```\n\nUse smart_* tools for code exploration, Read for non-code files. Mix freely.\n\n**Exploration then precision:**\n\n```\n1. smart_search(query=\"session\", path=\"./src\", max_results=10)\n   -> 10 ranked symbols: SessionMetadata, SessionQueueProcessor, SessionSummary...\n2. Pick the relevant one, unfold it\n```\n\n## Token Economics\n\n| Approach | Tokens | Use Case |\n|----------|--------|----------|\n| smart_outline | ~1,000-2,000 | \"What's in this file?\" |\n| smart_unfold | ~400-2,100 | \"Show me this function\" |\n| smart_search | ~2,000-6,000 | \"Find all X across the codebase\" |\n| search + unfold | ~3,000-8,000 | End-to-end: find and read (the primary workflow) |\n| Read (full file) | ~12,000+ | When you truly need everything |\n| Explore agent | ~39,000-59,000 | Cross-file synthesis with narrative |\n\n**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.\n\n## Language Support\n\nSmart-explore uses **tree-sitter AST parsing** for structural analysis. Unsupported file types fall back to text-based search.\n\n### Bundled Languages\n\n| Language | Extensions |\n|----------|-----------|\n| JavaScript | `.js`, `.mjs`, `.cjs` |\n| TypeScript | `.ts` |\n| TSX / JSX | `.tsx`, `.jsx` |\n| Python | `.py`, `.pyw` |\n| Go | `.go` |\n| Rust | `.rs` |\n| Ruby | `.rb` |\n| Java | `.java` |\n| C | `.c`, `.h` |\n| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hh` |\n\nFiles with unrecognized extensions are parsed as plain text — `smart_search` still works (grep-style), but `smart_outline` and `smart_unfold` will not extract structured symbols.\n\n### Custom Grammars (`.claude-mem.json`)\n\nYou can register additional tree-sitter grammars for file types not in the bundled list. Create or update `.claude-mem.json` in your project root:\n\n```json\n{\n  \"grammars\": {\n    \"solidity\": {\n      \"package\": \"tree-sitter-solidity\",\n      \"extensions\": [\".sol\"],\n      \"query\": \"solidity-query.scm\"\n    }\n  }\n}\n```\n\nEach key is a language name. `package` is the npm package of the tree-sitter grammar and `extensions` lists the file extensions it covers; the package must be installed in the project's `node_modules` (`npm install tree-sitter-solidity`). `query` (optional) is a path, relative to the config file, to a tree-sitter query whose captures (`@func`, `@cls`, `@method`, `@iface`, `@enm`, `@struct_def`, `@imp`) extract symbols. Without `query`, a minimal generic pattern is used — it only matches grammars that define `function_declaration`/`class_declaration` node types, and query compilation fails silently (0 symbols) for grammars that lack them, so a custom query is effectively required for most languages. Once registered, `smart_outline` and `smart_unfold` parse those extensions structurally instead of falling back to plain text.\n\n### Markdown Special Support\n\nMarkdown files (`.md`, `.mdx`) receive special handling beyond the generic plain-text fallback:\n\n- **`smart_outline`** — extracts headings (`#`, `##`, `###`) as the symbol tree. Use it to navigate long documents without reading the full file.\n- **`smart_search`** — searches within code fences as well as prose, so queries for function names inside ` ```ts ``` ` blocks work as expected.\n- **`smart_unfold`** — expands heading sections rather than function bodies; each section up to the next same-level heading is returned as a chunk.\n- **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.","author":"@thedotmack","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/thedotmack/claude-mem/tree/main/plugin/skills/smart-explore","license":"Apache-2.0","category":"coding","lang":"en","tokens":2146,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":[]}}