code-semantic-search
Semantic code search using Phase 1 vector embeddings and Phase 2 hybrid search.
- Installs
- 77
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/oimiragieo/agent-studio --skill code-semantic-search- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads code-semantic-search automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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.
FAQ
What does the code-semantic-search skill do?
Semantic code search using Phase 1 vector embeddings and Phase 2 hybrid search.
How do I install code-semantic-search?
Run npx skills add https://github.com/oimiragieo/agent-studio --skill code-semantic-search in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/code-semantic-search/ (personal) or .claude/skills/code-semantic-search/ (project).
Which AI agents can use code-semantic-search?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is code-semantic-search safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains code-semantic-search?
It is published by oimiragieo in oimiragieo/agent-studio. It has 77 recorded installs.
More from oimiragieo/agent-studio
pyqt6-ui-development-rules
oimiragieo/agent-studio
PyQt6 desktop GUI development rules -- signal/slot architecture, QSS theming, QThread concurrency, layout management, and cross-platform rendering. Enforces MVC separation and responsive UI patterns.
filesystem
oimiragieo/agent-studio
File system operations guidance - read, write, search, and manage files using Claude Code's built-in tools.
chrome-browser
oimiragieo/agent-studio
Open the skill to read its SKILL.md instructions.
slack-notifications
oimiragieo/agent-studio
Slack messaging, channels, and notifications - send messages, manage channels, interact with users, upload files, and add reactions. Use for team communication, incident notifications, and workflow alerts.
context-compressor
oimiragieo/agent-studio
Compress large context before reasoning to reduce token usage while preserving evidence. Use this whenever the user mentions huge files, long prompts, RAG payloads, prompt caching, expensive sessions, codebase context, chat history compaction, or wants the same answer quality with fewer tokens.
nodejs-expert
oimiragieo/agent-studio
Node.js backend expert including Express, NestJS, and async patterns
Popular ai & agents skills
google-agents-cli-publish
google/agents-cli
This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).
google-agents-cli-eval
google/agents-cli
This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).
skill-creator
anthropics/skills
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
codex-pet
prime-skills/runcomfy-agent-skills
Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.
full-output-enforcement
leonxlnx/taste-skill
Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.
executing-plans
obra/superpowers
Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available