/semantic-search

name: semantic-search
description: Semantic search for finding code by meaning using natural language queries. Orchestrates semantic-search-reader (search/find-similar/list-projects) and semantic-search-indexer (index/reindex/status) agents. Use for understanding unfamiliar codebases, finding similar implementations, or locating functionality by description rather than exact keywords. (project)
allowed-tools: Bash, Read, Glob, Grep

Semantic Search Skill

**Orchestrator for Semantic Code Intelligence via Agent Delegation**

This skill orchestrates two specialized agents for semantic search operations. It provides bash scripts that import Python modules from the claude-context-local library (**NOT an MCP server** - no server process runs, just Python imports via PYTHONPATH). Unlike traditional text-based search (Grep) or pattern matching (Glob), semantic search understands the **meaning** of content, finding functionally similar text even when using different wording, variable names, or patterns.

The skill uses the library's venv Python interpreter to import merkle, chunking, and embedding modules, enabling semantic search, indexing, and similarity finding across any text content (code, docs, markdown, configs).

🎬 Orchestration Instructions

**When this skill is active, you MUST spawn the appropriate agent via Task tool.**

This skill uses a **2-agent architecture** for token optimization:

• **semantic-search-reader**: Handles READ operations (search, find-similar, list-projects)
• **semantic-search-indexer**: Handles WRITE operations (index, incremental-reindex, status)

Decision Logic: Which Agent to Spawn?

| User Request Contains | Operation Type | Agent to Spawn | |----------------------|----------------|----------------| | "find X", "search for Y", "where is Z" | **search** | semantic-search-reader | | "find similar to...", "similar chunks" | **find-similar** | semantic-search-reader | | "what projects", "list indexed", "show projects" | **list-projects** | semantic-search-reader | | "index this", "create index", "full reindex" | **index** | semantic-search-indexer | | "incremental reindex", "auto reindex", "update index" | **incremental-reindex** | semantic-search-indexer | | "check index", "index status", "is it indexed" | **status** | semantic-search-indexer |

Agent Spawn Examples

**Example 1: Search Operation** (semantic-search-reader)

Task(
    subagent_type="semantic-search-reader",
    description="Search project semantically",
    prompt="""You are the semantic-search-reader agent.

Operation: search
Query: "user authentication logic"
K: 10
Project: /path/to/project

Execute the search operation using scripts/search and return interpreted results with explanations."""
)

**Example 2: Index Operation** (semantic-search-indexer)

Task(
    subagent_type="semantic-search-indexer",
    description="Index project for semantic search",
    prompt="""You are the semantic-search-indexer agent.

Operation: index
Directory: /path/to/project
Full: true

Execute the indexing operation using scripts/incremental-reindex and return interpreted results with statistics."""
)

**Example 3: Incremental Reindex Operation** (semantic-search-indexer)

Task(
    subagent_type="semantic-search-indexer",
    description="Incremental reindex with change detection",
    prompt="""You are the semantic-search-indexer agent.

Operation: incremental-reindex
Directory: /path/to/project
Max Age: 360  # minutes (6 hours)

Execute smart auto-reindexing using scripts/incremental-reindex.
This will detect changed files using Merkle tree, then auto-fallback to full reindex.
Return statistics showing total files indexed and total chunks."""
)

**Example 4: Find Similar** (semantic-search-reader)

Task(
    subagent_type="semantic-search-reader",
    description="Find similar content chunks",
    prompt="""You are the semantic-search-reader agent.

Operation: find-similar
Chunk ID: "src/auth.py:45-67:function:authenticate"
K: 5
Project: /path/to/project

Execute the find-similar operation using scripts/find-similar and return interpreted results."""
)

**Example 5: Status Check** (semantic-search-indexer)

Task(
    subagent_type="semantic-search-indexer",
    description="Check semantic index status",
    prompt="""You are the semantic-search-indexer agent.

Operation: status
Project: /path/to/project

Execute the status operation using scripts/status and return interpreted results with statistics."""
)

Important Notes

• **NEVER run bash scripts directly** - always spawn the appropriate agent
• **Agents handle error interpretation** - they convert JSON errors to natural language
• **Token optimization**: Agent execution happens in separate context (saves YOUR tokens)
• **Wait for agent completion** - agents return summarized results, not raw JSON

🎯 When to Use This Skill

✅ Use Semantic Search When:

**1. Exploring Unfamiliar Projects**

• "How does this codebase handle user authentication?"
• "Where is database connection pooling implemented?"
• "Show me error handling patterns in this project"
• "Find documentation about the architecture"

**2. Finding Functionality Without Keywords**

• Looking for implementations but don't know the exact function names
• Need to find code that "does X" without knowing how it's named
• Searching across multiple languages/frameworks with different conventions

**3. Discovering Similar Code**

• "Find code similar to this payment processing logic"
• "Are there other implementations of rate limiting?"
• "What other modules use this pattern?"

**4. Cross-Reference Discovery**

• Finding all authentication methods in a polyglot codebase
• Locating retry logic across different services
• Identifying validation patterns in various modules

**5. Searching Documentation & Configuration**

• "Find documentation explaining the deployment process"
• "Locate configuration examples for data