
Code Semantic Search
- 75 installs
- 36 repo stars
- Updated July 14, 2026
- oimiragieo/agent-studio
Helps with ai & agent building tasks.
About
code-semantic-search is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted development.
- code-semantic-search
- AI & Agent Building
- AI-coding skill
Code Semantic Search by the numbers
- 75 all-time installs (skills.sh)
- +1 installs in the week ending Aug 4, 2026 (Skillselion tracking)
- Ranked #5,460 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
- Data as of Aug 4, 2026 (Skillselion catalog sync)
npx skills add https://github.com/oimiragieo/agent-studio --skill code-semantic-searchAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 75 |
|---|---|
| repo stars | ★ 36 |
| Last updated | July 14, 2026 |
| Repository | oimiragieo/agent-studio ↗ |
What it does
Helps with ai & agent building tasks.
Files
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:
1. Hybrid (Default):
- Combines semantic + structural search
- Best accuracy (95%+)
- Slightly slower but still <150ms
- Recommended for all searches
2. Semantic-Only:
- Uses only Phase 1 semantic vectors
- Fastest (<50ms)
- Good for conceptual searches
- Use when structure doesn't matter
3. 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
1. 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. 2. 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. 3. 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. 4. 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. 5. 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.
Invoke the code-semantic-search skill and follow it exactly as presented to you
'use strict';
/**
* Post-execute hook for code-semantic-search
* Auto-generated by enterprise-bundle-scaffolder
*
* Records metrics after skill execution.
*/
function postExecute(_context) {
// Record execution metrics
return { ok: true, skill: 'code-semantic-search' };
}
module.exports = { postExecute };
'use strict';
/**
* Pre-execute hook for code-semantic-search
* Auto-generated by enterprise-bundle-scaffolder
*
* Validates inputs before skill execution.
*/
function preExecute(context) {
// Validate skill invocation context
if (!context || typeof context !== 'object') {
return { allow: true, message: 'code-semantic-search: no context to validate' };
}
return { allow: true };
}
module.exports = { preExecute };
code-semantic-search Research Requirements
Generated: 2026-02-28
Skill Description
Semantic code search using Phase 1 vector embeddings and Phase 2 hybrid search.
Research Areas
- Current best practices for code-semantic-search
- Industry standards and tooling
- Integration patterns
Source References
- To be populated by skill-updater research phase
code-semantic-search Rules
Purpose
Semantic code search using Phase 1 vector embeddings and Phase 2 hybrid search.
Best Practices
- Follow established patterns
- Validate inputs at boundaries
Integration Points
See SKILL.md for complete documentation.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "code-semantic-searchInput",
"description": "Input schema for Semantic code search using Phase 1 vector embeddings and Phase 2 hybrid search.",
"type": "object",
"additionalProperties": true,
"properties": {
"target": {
"type": "string",
"description": "Target file or path for the skill to operate on"
},
"options": {
"type": "object",
"description": "Additional options for skill execution",
"additionalProperties": true
}
}
}
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "code-semantic-searchOutput",
"type": "object",
"additionalProperties": true,
"properties": {
"ok": {
"type": "boolean"
},
"summary": {
"type": "string"
}
}
}
'use strict';
const fs = require('node:fs');
const path = require('node:path');
const { spawn } = require('node:child_process');
function findProjectRoot(start = __dirname) {
let dir = start;
while (dir !== path.parse(dir).root) {
if (fs.existsSync(path.join(dir, '.claude', 'CLAUDE.md'))) return dir;
dir = path.dirname(dir);
}
return process.cwd();
}
function parseArgs(argv) {
const args = [];
const options = {};
for (let i = 0; i < argv.length; i++) {
const token = argv[i];
if (!token.startsWith('--')) {
args.push(token);
continue;
}
const key = token.slice(2);
const next = argv[i + 1];
const hasValue = next && !next.startsWith('--');
options[key] = hasValue ? argv[++i] : true;
}
return { args, options };
}
function runCli(rawArgs, projectRoot = findProjectRoot()) {
const cliPath = path.join(projectRoot, '.claude', 'tools', 'cli', 'hybrid-search.cjs');
if (!fs.existsSync(cliPath)) {
throw new Error(`hybrid-search CLI missing at ${cliPath}`);
}
const child = spawn(process.execPath, [cliPath, ...rawArgs], {
cwd: projectRoot,
stdio: 'inherit',
windowsHide: true,
});
child.on('close', code => process.exit(code ?? 1));
}
function main(input = {}) {
const query = String(input.query || '').trim();
const mode = String(input.mode || 'hybrid').toLowerCase();
const args = [];
if (!query && mode !== 'structure' && mode !== 'file') {
return {
ok: false,
error: 'query is required unless mode is structure or file',
usage: 'node main.cjs --query "auth middleware"',
};
}
if (mode === 'structure') {
args.push('--structure');
} else if (mode === 'file') {
if (!input.filePath) {
return { ok: false, error: 'filePath is required for mode=file' };
}
args.push('--file', String(input.filePath));
if (input.start !== undefined) args.push(String(input.start));
if (input.end !== undefined) args.push(String(input.end));
} else {
args.push(query);
}
return {
ok: true,
delegated: 'hybrid-search',
args,
command: `node .claude/tools/cli/hybrid-search.cjs ${args.join(' ')}`.trim(),
};
}
if (require.main === module) {
const { args, options } = parseArgs(process.argv.slice(2));
if (options.help) {
console.log(`
code-semantic-search
Usage:
node main.cjs --query "<text>"
node main.cjs --mode structure
node main.cjs --mode file --filePath "src/index.ts" --start 1 --end 40
`);
process.exit(0);
}
const result = main({
query: options.query || args.join(' '),
mode: options.mode || 'hybrid',
filePath: options.filePath,
start: options.start,
end: options.end,
});
if (!result.ok) {
console.error(result.error);
process.exit(1);
}
runCli(result.args);
}
module.exports = { main, parseArgs, runCli, findProjectRoot };
code-semantic-search Implementation Template
Goal
- Define target outcome and acceptance criteria.
TDD
1. Red 2. Green 3. Refactor
Verification
- lint
- format
- targeted tests