code-semantic-search
Semantic code search using Phase 1 vector embeddings and Phase 2 hybrid search.
How do I install this agent skill?
npx skills add https://github.com/oimiragieo/agent-studio --skill code-semantic-searchIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill performs semantic code search by wrapping a CLI tool located in the project's hidden directory. It uses a runtime-computed path to locate its internal tooling and processes source code content, which presents a surface for potential indirect prompt injection.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
2/10 files flagged
What does this agent skill do?
Code Semantic Search
Overview
Semantic code search using Phase 1 vector embeddings and Phase 2 hybrid search (semantic + structural). Find code by meaning, not just keywords.
Core principle: Search code by what it does, not what it's called.
Phase 2: Hybrid Search
This skill now supports three search modes:
-
Hybrid (Default):
- Combines semantic + structural search
- Best accuracy (95%+)
- Slightly slower but still <150ms
- Recommended for all searches
-
Semantic-Only:
- Uses only Phase 1 semantic vectors
- Fastest (<50ms)
- Good for conceptual searches
- Use when structure doesn't matter
-
Structural-Only:
- Uses only ast-grep patterns
- Precise for exact matches
- Best for finding function/class definitions
- Use when you need exact structural patterns
Performance Comparison
| Mode | Speed | Accuracy | Best For |
|---|---|---|---|
| Hybrid | <150ms | 95% | General search |
| Semantic-only | <50ms | 85% | Concepts |
| Structural-only | <50ms | 100% | Exact patterns |
| Phase 1 only | <50ms | 80% | Legacy (fallback) |
When to Use
Always:
- Finding authentication logic without knowing function names
- Searching for error handling patterns
- Locating database queries
- Finding similar code to a concept
- Discovering implementation patterns
Don't Use:
- Exact text matching (use Grep instead)
- File name searches (use Glob instead)
- Simple keyword searches (use ripgrep instead)
Usage Examples
Hybrid Search (Recommended)
// Basic hybrid search
Skill({ skill: 'code-semantic-search', args: 'find authentication logic' });
// With options
Skill({
skill: 'code-semantic-search',
args: 'database queries',
options: {
mode: 'hybrid',
language: 'javascript',
limit: 10,
},
});
Semantic-Only Search
// Fast conceptual search
Skill({
skill: 'code-semantic-search',
args: 'find authentication',
options: { mode: 'semantic-only' },
});
Structural-Only Search
// Exact pattern matching
Skill({
skill: 'code-semantic-search',
args: 'find function authenticate',
options: { mode: 'structural-only' },
});
Implementation Reference
Hybrid Search: .claude/lib/code-indexing/hybrid-search.cjs
Query Analysis: .claude/lib/code-indexing/query-analyzer.cjs
Result Ranking: .claude/lib/code-indexing/result-ranker.cjs
Integration Points
- developer: Code exploration, implementation discovery
- architect: System understanding, pattern analysis
- code-reviewer: Finding similar patterns, consistency checks
- reverse-engineer: Understanding unfamiliar codebases
- researcher: Research existing implementations
Iron Laws
- ALWAYS use hybrid mode (semantic + structural) for general searches — semantic-only misses exact matches; structural-only misses conceptual variants; hybrid provides 95% accuracy vs 85% for single mode.
- ALWAYS use ripgrep/keyword search first for fast keyword discovery — semantic search is for meaning-based queries; exact strings, function names, and filenames are found faster with ripgrep.
- NEVER use semantic search without a meaningful natural-language query — single-word or code-syntax queries produce poor semantic results; describe what the code does, not what it's called.
- ALWAYS combine with code-structural-search for precision refinement — start broad with semantic discovery, then use ast-grep patterns to find exact structural matches from the semantic results.
- NEVER ignore low-similarity results without checking them — similarity scores are approximations; a 0.7 score result may be more relevant than a 0.9 score result for uncommon patterns.
Anti-Patterns
| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| Semantic search for exact string matching | Slower and less accurate than text search | Use ripgrep/Grep for exact keyword matching |
| Single-word queries ("auth") | Too vague for semantic matching; returns noise | Use natural-language descriptions ("authentication token validation logic") |
| Using semantic-only mode for general searches | Misses structural variants; 85% vs 95% accuracy | Use hybrid mode (default) for general queries |
| Ignoring search results that don't match expectations | Semantic results find surprising-but-relevant code | Read all results; unexpected matches are often the most valuable |
| Not combining with structural search | Finds concepts but not exact patterns | Use semantic for discovery → structural for precision |
Memory Protocol (MANDATORY)
Before starting:
Read .claude/context/memory/learnings.md
After completing:
- New pattern ->
.claude/context/memory/learnings.md - Issue found ->
.claude/context/memory/issues.md - Decision made ->
.claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it's not in memory, it didn't happen.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/oimiragieo/agent-studio/code-semantic-search">View code-semantic-search on skillZs</a>