// Intent-based code discovery for CLI AI agents using semantic search MCP tools. Use when finding code by what it does (not what it's called), exploring unfamiliar areas, or understanding feature implementations. Mandatory for code discovery tasks when you have MCP access.
| name | mcp-semantic-search |
| description | Intent-based code discovery for CLI AI agents using semantic search MCP tools. Use when finding code by what it does (not what it's called), exploring unfamiliar areas, or understanding feature implementations. Mandatory for code discovery tasks when you have MCP access. |
| allowed-tools | ["Grep","Read","Glob"] |
| version | 1.2.0 |
Semantic code search for CLI AI agents that enables AI-powered codebase exploration using natural language queries instead of keyword searches. Available exclusively for CLI AI agents with MCP (Model Context Protocol) support.
Use this skill when:
Exploring unfamiliar code
Finding by behavior/intent
Understanding patterns
Discovering cross-file relationships
Code discovery tasks for CLI AI agents
Use different tools instead:
Known exact file paths → Use Read tool
❌ semantic_search("Find hero_video.js content")
✅ Read("src/hero/hero_video.js")
Specific symbol searches → Use Grep tool
❌ semantic_search("Find all calls to initVideoPlayer")
✅ Grep("initVideoPlayer", output_mode="content")
Simple keyword searches → Use Grep tool
❌ semantic_search("Find all TODO comments")
✅ Grep("TODO:", output_mode="content")
File structure exploration → Use Glob tool
❌ semantic_search("Show me all JavaScript files")
✅ Glob("**/*.js")
IDE integrations → NOT SUPPORTED
See Section 2 Smart Router Quick Reference for a decision flowchart on tool selection.
Activate this skill when user asks:
Do NOT activate for:
/semantic_search [args]
│
├─► No args
│ └─► Show usage help
│
├─► Natural language query (2+ words, code terms, question words)
│ └─► SEARCH ACTION: Execute semantic search
│
├─► "index" | "reindex" | "rebuild"
│ └─► INDEX ACTION: Rebuild vector index
│
├─► "status" | "health"
│ └─► STATUS ACTION: Show index health
│
└─► Single ambiguous word
└─► SEARCH ACTION (assume search intent)
KNOWN file path → Use Read tool directly
KNOWN symbol/pattern → Use Grep tool
FILE patterns needed → Use Glob tool
UNKNOWN what code does → Use semantic_search
def route_semantic_search_resources(task):
# ──────────────────────────────────────────────────────────────────
# TOOL SELECTION GUIDANCE
# Purpose: Decision framework for semantic search vs grep vs glob
# Key Insight: When to use each tool based on knowledge and intent
# ──────────────────────────────────────────────────────────────────
if task.unsure_which_tool:
return load("references/tool_comparison.md") # semantic vs grep vs glob decision
# ──────────────────────────────────────────────────────────────────
# QUERY WRITING HELP
# Purpose: Effective query writing guide + Categorized example queries
# Key Insight: Describe behavior in natural language for best results
# ──────────────────────────────────────────────────────────────────
if task.needs_query_examples or task.query_not_working:
load("references/query_patterns.md") # effective query writing guide
return load("assets/query_examples.md") # 9 categories of real queries
# ──────────────────────────────────────────────────────────────────
# ARCHITECTURE / SYSTEM UNDERSTANDING
# Purpose: System architecture and data flow
# Key Insight: Two-component system: Indexer + MCP Server + Vector DB
# ──────────────────────────────────────────────────────────────────
if task.needs_architecture_info:
return load("references/architecture.md") # indexer + MCP server + vector DB
Two semantic search MCP tools available:
semantic_search - Search current project semantically
visit_other_project - Search other indexed projects
Query structure - describe what code does:
// Good: Natural language, behavior-focused
semantic_search("Find code that validates email addresses in contact forms")
// Good: Question format
semantic_search("How do we handle page transitions?")
// Good: Feature discovery
semantic_search("Find cookie consent implementation")
// Bad: Grep syntax
semantic_search("grep validateEmail") // ❌ Use grep tool instead
// Bad: Known file path
semantic_search("Show me hero_video.js") // ❌ Use Read tool instead
Goal: Find email validation logic
// Step 1: Use semantic search
semantic_search("Find code that validates email addresses in contact forms")
// Expected results:
// - src/form/form_validation.js (ranked #1)
// - src/utils/email_validator.js (ranked #2)
// - Code snippets with validation logic
// Step 2: Read full context
Read("src/form/form_validation.js")
// Step 3: Analyze and make changes
Edit(...) or Write(...)
Why it works: Query describes behavior (validates email), context (contact forms), allowing semantic search to find relevant code.
Goal: Find what code depends on video player
// Use relationship query
semantic_search("What code depends on the video player?")
// Expected results:
// - src/components/hero_section.js (uses video player)
// - src/animations/hero_animations.js (triggers on video events)
// - Code snippets showing imports and usage
// Follow up: Read specific files
Read("src/components/hero_section.js")
Why it works: Semantic search understands dependencies and can find related code across files.
Do:
Don't:
For more query patterns, see: query_patterns.md
Results are reranked for relevance:
ALWAYS use for intent-based discovery
ALWAYS use natural language
ALWAYS provide context in queries
ALWAYS combine with Read tool
ALWAYS check for MCP availability
NEVER use for known file paths
NEVER use for exact symbol searches
NEVER use grep/find syntax
NEVER skip validation of MCP access
NEVER use for file structure exploration
ESCALATE IF MCP server unavailable
ESCALATE IF results consistently irrelevant
/semantic_search stats or ask user to run /semantic_search startESCALATE IF uncertain about tool selection
ESCALATE IF IDE integration requested
Task complete when:
Required MCP tools:
semantic_search - Semantic code searchvisit_other_project - Cross-project searchMCP server: semantic-search (Python)
Availability: CLI AI agents only (OpenCode, GitHub Copilot CLI, Cline, Kilo CLI)
NOT available: IDE integrations (GitHub Copilot in VS Code/IDEs)
Read tool:
Grep tool:
Glob tool:
Note on Code Mode:
mcp__semantic_search__semantic_search(), mcp__semantic_search__visit_other_project() directlyIndexer: codebase-index-cli (Node.js)
Vector Database: SQLite (.codebase/vectors.db)
Voyage AI API:
Must be indexed first:
codesql -start to create .codebase/vectors.db/semantic_search stats to verify indexing statusCurrent anobel.com index (as of 2025-11-25):
✅ Works with (CLI AI agents):
❌ Does NOT work with (IDE integrations):
Reason: Different systems - semantic search is for CLI AI agents helping you via chat, not autocomplete while typing.
Remember: This skill operates as an intent-based discovery engine. It enables natural language exploration of the codebase to find functionality by behavior rather than keyword.