Smart Explore Skill
Purpose
Enable AI agents to explore codebases efficiently by viewing structural outlines, searching for symbols, and extracting specific implementations — without reading entire files. This dramatically reduces token consumption when navigating large projects.
When to Use
- Understanding a new file: Use
outline instead of reading the full file
- Finding where something is defined: Use
search to locate symbols across the project
- Reading a specific function: Use
unfold to extract just that function's code
Token Savings
| Method |
Typical Token Cost |
Notes |
| Read full file |
~12,000+ |
All content, most irrelevant |
| Outline |
~1,000-2,000 |
Structural skeleton only |
| Search |
~2,000-6,000 |
Symbol locations across codebase |
| Unfold |
~400-2,100 |
Exact function/class source |
Savings: 4-18x compared to reading full files.
Available Commands
1. Outline — Structural Skeleton
View all symbols (functions, classes, interfaces, exports) in a file without reading the full source:
heraspec explore outline src/core/memory/memory-store.ts
Output example:
## 📄 src/core/memory/memory-store.ts
*typescript | 285 lines | ~71250 tokens*
🏛️ export class MemoryStore (L20-285)
↳ open() (L32-58)
↳ close() (L63-68)
↳ addObservation(input) (L88-120)
↳ getObservationById(id) (L125-132)
↳ getRecentObservations(project, limit) (L140-160)
↳ addSummary(input) (L165-195)
↳ getStatus(project) (L200-260)
2. Search — Find Symbols Across Codebase
Search for functions, classes, interfaces by name across the project:
heraspec explore search "MemoryStore" src/
heraspec explore search "addObservation" src/ --limit 10
Output example:
## Symbol Search: "MemoryStore" (3 results)
| Rel | Type | Name | File | Lines |
|-----|------|------|------|-------|
| 100% | 🏛️ class | MemoryStore | src/core/memory/memory-store.ts | L20-285 |
| 60% | ⚡ function | MemoryStoreFactory | src/core/memory/index.ts | L10-15 |
| 40% | 📌 variable | memoryStore | src/commands/memory.ts | L25-25 |
3. Unfold — Extract Specific Symbol Source
Read just the implementation of a specific function or class:
heraspec explore unfold src/core/memory/memory-store.ts addObservation
Output example:
## method: addObservation
*src/core/memory/memory-store.ts:L88-120 | ~800 tokens (vs ~71250 full file)*
addObservation(input: ObservationInput): Observation {
this.ensureOpen();
// ... full implementation
}
Supported Languages
| Language |
Extensions |
Symbols Detected |
| TypeScript |
.ts, .tsx |
class, interface, type, enum, function, method, variable |
| JavaScript |
.js, .jsx, .mjs |
class, function, method, variable |
| Python |
.py |
class, function, method, variable |
| PHP |
.php |
class, interface, function |
| Go |
.go |
struct, interface, func |
| Rust |
.rs |
struct, trait, enum, fn |
| Java |
.java |
class, interface, method |
| C# |
.cs |
class, interface, method |
| Vue |
.vue |
Same as TypeScript |
| Svelte |
.svelte |
Same as TypeScript |
Workflow for AI Agents
Exploration Strategy
Need to understand a file?
├── Step 1: heraspec explore outline <file>
│ → See all functions, classes, interfaces (~1K tokens)
├── Step 2: Identify relevant symbols from outline
├── Step 3: heraspec explore unfold <file> <symbol>
│ → Read just the relevant function (~400-2K tokens)
└── Only read full file if you need comprehensive understanding
Need to find where something is?
├── heraspec explore search "<name>" <path>
│ → Find symbol locations across codebase
├── Then use unfold to read specific implementations
└── Avoid grep-like full-text search when possible
Key Principles
- Outline first, read later: Always check the outline before reading full files
- Unfold specific symbols: Don't read entire files when you only need one function
- Search before browsing: Find what you need by name rather than scanning directories
- Skip node_modules, dist, .git: Automatically excluded from search
Limitations
- Uses regex-based parsing (not AST) — may miss some complex patterns
- Symbol end-line detection is approximate (brace/indent counting)
- Method detection within classes requires proper indentation
- Does not handle dynamically generated code or macros
1---2name: smart-explore3description: Token-efficient code exploration — view file structure, search symbols, and read specific implementations without loading full files. Reduces token usage by 4-18x compared to reading entire files.4---56# Smart Explore Skill78## Purpose910Enable AI agents to **explore codebases efficiently** by viewing structural outlines, searching for symbols, and extracting specific implementations — without reading entire files. This dramatically reduces token consumption when navigating large projects.1112## When to Use1314- **Understanding a new file**: Use `outline` instead of reading the full file15- **Finding where something is defined**: Use `search` to locate symbols across the project16- **Reading a specific function**: Use `unfold` to extract just that function's code1718## Token Savings1920| Method | Typical Token Cost | Notes |21|--------|-------------------|-------|22| Read full file | ~12,000+ | All content, most irrelevant |23| **Outline** | ~1,000-2,000 | Structural skeleton only |24| **Search** | ~2,000-6,000 | Symbol locations across codebase |25| **Unfold** | ~400-2,100 | Exact function/class source |2627**Savings: 4-18x** compared to reading full files.2829## Available Commands3031### 1. Outline — Structural Skeleton3233View all symbols (functions, classes, interfaces, exports) in a file without reading the full source:3435```bash36heraspec explore outline src/core/memory/memory-store.ts37```3839**Output example:**40```41## 📄 src/core/memory/memory-store.ts42*typescript | 285 lines | ~71250 tokens*4344🏛️ export class MemoryStore (L20-285)45 ↳ open() (L32-58)46 ↳ close() (L63-68)47 ↳ addObservation(input) (L88-120)48 ↳ getObservationById(id) (L125-132)49 ↳ getRecentObservations(project, limit) (L140-160)50 ↳ addSummary(input) (L165-195)51 ↳ getStatus(project) (L200-260)52```5354### 2. Search — Find Symbols Across Codebase5556Search for functions, classes, interfaces by name across the project:5758```bash59heraspec explore search "MemoryStore" src/60heraspec explore search "addObservation" src/ --limit 1061```6263**Output example:**64```65## Symbol Search: "MemoryStore" (3 results)6667| Rel | Type | Name | File | Lines |68|-----|------|------|------|-------|69| 100% | 🏛️ class | MemoryStore | src/core/memory/memory-store.ts | L20-285 |70| 60% | ⚡ function | MemoryStoreFactory | src/core/memory/index.ts | L10-15 |71| 40% | 📌 variable | memoryStore | src/commands/memory.ts | L25-25 |72```7374### 3. Unfold — Extract Specific Symbol Source7576Read just the implementation of a specific function or class:7778```bash79heraspec explore unfold src/core/memory/memory-store.ts addObservation80```8182**Output example:**83```84## method: addObservation85*src/core/memory/memory-store.ts:L88-120 | ~800 tokens (vs ~71250 full file)*8687 addObservation(input: ObservationInput): Observation {88 this.ensureOpen();89 // ... full implementation90 }91```9293## Supported Languages9495| Language | Extensions | Symbols Detected |96|----------|-----------|-----------------|97| TypeScript | `.ts`, `.tsx` | class, interface, type, enum, function, method, variable |98| JavaScript | `.js`, `.jsx`, `.mjs` | class, function, method, variable |99| Python | `.py` | class, function, method, variable |100| PHP | `.php` | class, interface, function |101| Go | `.go` | struct, interface, func |102| Rust | `.rs` | struct, trait, enum, fn |103| Java | `.java` | class, interface, method |104| C# | `.cs` | class, interface, method |105| Vue | `.vue` | Same as TypeScript |106| Svelte | `.svelte` | Same as TypeScript |107108## Workflow for AI Agents109110### Exploration Strategy111112```113Need to understand a file?114├── Step 1: heraspec explore outline <file>115│ → See all functions, classes, interfaces (~1K tokens)116├── Step 2: Identify relevant symbols from outline117├── Step 3: heraspec explore unfold <file> <symbol>118│ → Read just the relevant function (~400-2K tokens)119└── Only read full file if you need comprehensive understanding120121Need to find where something is?122├── heraspec explore search "<name>" <path>123│ → Find symbol locations across codebase124├── Then use unfold to read specific implementations125└── Avoid grep-like full-text search when possible126```127128### Key Principles1291301. **Outline first, read later**: Always check the outline before reading full files1312. **Unfold specific symbols**: Don't read entire files when you only need one function1323. **Search before browsing**: Find what you need by name rather than scanning directories1334. **Skip node_modules, dist, .git**: Automatically excluded from search134135## Limitations136137- Uses regex-based parsing (not AST) — may miss some complex patterns138- Symbol end-line detection is approximate (brace/indent counting)139- Method detection within classes requires proper indentation140- Does not handle dynamically generated code or macros
PolyXGO