osgrep
Semantic code search using natural language queries. Use when users ask "where is X implemented", "how does Y work", "find the logic for Z", or need to locate code by concept rather than exact text. Returns file paths with line numbers and code snippets.
About this skill
The `osgrep` skill provides AI agents with the powerful capability of semantic code search. Unlike traditional keyword-based search, `osgrep` understands the conceptual meaning behind natural language queries, allowing agents to find code related to abstract ideas like 'how are plugins loaded' or 'where is authentication handled.' This is invaluable for navigating complex or unfamiliar codebases where exact function names or file structures are unknown. Agents can use `osgrep` to quickly pinpoint relevant sections of code, whether they are looking for broad architectural patterns or specific implementation details. The skill guides the agent on how to formulate effective queries for different scenarios, from initially surveying a codebase to refining searches for precise logic. It returns file paths with line numbers and truncated code snippets, providing a starting point for deeper investigation. By leveraging `osgrep`, AI agents can significantly reduce the time and effort required to understand, debug, or modify code. It empowers them to answer user questions about code structure, functionality, and implementation details by intelligently searching the underlying codebase.
Best use case
The primary use case for `osgrep` is enabling AI agents to understand and interact with codebases at a conceptual level. Developers, maintainers, and code auditors benefit significantly, as the agent can assist in tasks like onboarding to new projects, identifying code vulnerabilities, or finding specific feature implementations without requiring exhaustive manual exploration. It's particularly useful when dealing with large, legacy, or poorly documented projects.
Semantic code search using natural language queries. Use when users ask "where is X implemented", "how does Y work", "find the logic for Z", or need to locate code by concept rather than exact text. Returns file paths with line numbers and code snippets.
A concise list of file paths with line numbers and brief code snippets that semantically match the natural language query, guiding the agent to the relevant code sections.
Practical example
Example input
osgrep "logic for merging user and default configuration"
Example output
src/config/merge.js:15-28:
```javascript
const mergeConfigs = (userConfig, defaultConfig) => {
// Deep merge logic here
return { ...defaultConfig, ...userConfig };
};
```
packages/cli/src/commands/init.js:50-55:
```javascript
const merged = mergeConfigs(readUserConfig(), getDefaultConfig());
// Apply merged configuration
```When to use this skill
- To find code by concept, behavior, or abstract ideas (e.g., 'where is auth validated').
- When trying to understand architectural patterns or system-level integrations.
- To locate specific, complex implementation logic or algorithms.
- When traditional text search yields too many irrelevant results or misses conceptual matches.
When not to use this skill
- When an exact text string or regex search is sufficient and more precise.
- To get the full context of a very long file immediately (snippets are truncated).
- For trivial searches where file paths are already known or easily guessable.
- When needing to modify code directly without prior reading; this tool is for discovery.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/osgrep-skill/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How osgrep Compares
| Feature / Agent | osgrep | Standard Approach |
|---|---|---|
| Platform Support | Claude | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | medium | N/A |
Frequently Asked Questions
What does this skill do?
Semantic code search using natural language queries. Use when users ask "where is X implemented", "how does Y work", "find the logic for Z", or need to locate code by concept rather than exact text. Returns file paths with line numbers and code snippets.
Which AI agents support this skill?
This skill is designed for Claude.
How difficult is it to install?
The installation complexity is rated as medium. You can find the installation instructions above.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
AI Agents for Coding
Browse AI agent skills for coding, debugging, testing, refactoring, code review, and developer workflows across Claude, Cursor, and Codex.
Best AI Skills for Claude
Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.
ChatGPT vs Claude for Agent Skills
Compare ChatGPT and Claude for AI agent skills across coding, writing, research, and reusable workflow execution.
SKILL.md Source
## When to Use Use this to find code by **concept** or **behavior** (e.g., "where is auth validated", "how are plugins loaded"). *Note: This tool prioritizes finding the right files and locations in the code. Snippets are truncated (max 16 lines) and are often just previews.* Example: ```bash osgrep "how are plugins loaded" osgrep "how are plugins loaded" packages/transformers.js/src ``` ## Strategy for Different Query Types ### For **Architectural/System-Level Questions** (auth, LSP integration, file watching) 1. **Search Broadly First:** Use a conceptual query to map the landscape. * `osgrep "authentication authorization checks"` 2. **Survey the Results:** Look for patterns across multiple files: * Are checks in middleware? Decorators? Multiple services? * Do file paths suggest different layers (gateway, handlers, utils)? 3. **Read Strategically:** Pick 2-4 files that represent different aspects: * Read the main entry point * Read representative middleware/util files * Follow imports if architecture is unclear 4. **Refine with Specific Searches:** If one aspect is unclear: * `osgrep "session validation logic"` * `osgrep "API authentication middleware"` ### For **Targeted Implementation Details** (specific function, algorithm) 1. **Search Specifically:** Ask about the precise logic. * `osgrep "logic for merging user and default configuration"` 2. **Evaluate the Semantic Match:** * Does the snippet look relevant? * **Crucial:** If it ends in `...` or cuts off mid-logic, **read the file**. 3. **One Search, One Read:** Use osgrep to pinpoint the best file, then read it fully. ## Output Format Returns: `path/to/file:line [Tags] Code Snippet` - `[Definition]`: Semantic search detected a class/function here. High relevance. - `...`: **Truncation Marker**. Snippet is incomplete—use `read_file` for full context. ## Tips - **Trust the Semantics:** You don't need exact names. `osgrep "how does the server start"` works better than guessing `osgrep "server.init"`. - **Watch for Distributed Patterns:** If results span 5+ files in different directories, the feature is likely architectural—survey before diving deep. - **Scope When Possible:** Use path constraints to focus: `osgrep "auth" src/server/` - **Don't Over-Rely on Snippets:** For architectural questions, snippets are signposts, not answers. Read the key files. - **"Still Indexing...":** If you see this, please stop, alert the user that the index is ongoing and ask them if they wish to proceed. Results will be partial until the index is complete.
Related Skills
laravel-expert
Senior Laravel Engineer role for production-grade, maintainable, and idiomatic Laravel solutions. Focuses on clean architecture, security, performance, and modern standards (Laravel 10/11+).
webmcp
This skill guides AI agents in implementing WebMCP within web projects, enabling browser-native structured tools for AI interaction using JavaScript or HTML APIs.
Prompt Coach
Analyze your Claude Code session logs to improve prompt quality, optimize tool usage, and enhance your skills as an AI-native engineer.
nextjs
Provides comprehensive Next.js routing capabilities, including typed routes, helpers for `PageProps` and `LayoutProps`, and `nuqs` for managing URL state.
react
This AI agent skill guides the generation of modern React components, incorporating best practices such as destructured props, leveraging compiler optimizations, and proper use of React Effects. It also ensures compatibility and utilizes Tailwind CSS v4 syntax.
just
Use `just` to save and run project-specific commands. Use when the user mentions `justfile`, `recipe`, or needs a simple alternative to `make` for task automation.
chrome-debug
This skill empowers AI agents to debug web applications and inspect browser behavior using the Chrome DevTools Protocol (CDP), offering both collaborative (headful) and automated (headless) modes.
worktree-manager
Create, manage, and cleanup git worktrees with Claude Code agents across all projects. USE THIS SKILL when user says "create worktree", "spin up worktrees", "new worktree for X", "worktree status", "cleanup worktrees", "sync worktrees", or wants parallel development branches. Also use when creating PRs from a worktree branch (to update registry with PR number). Handles worktree creation, dependency installation, validation, agent launching in Ghostty, and global registry management.
clearshot
Structured screenshot analysis for UI implementation and critique. Analyzes every UI screenshot with a 5×5 spatial grid, full element inventory, and design system extraction — facts and taste together, every time. Escalates to full implementation blueprint when building. Trigger on any digital interface image file (png, jpg, gif, webp — websites, apps, dashboards, mockups, wireframes) or commands like 'analyse this screenshot,' 'rebuild this,' 'match this design,' 'clone this.' Skip for non-UI images (photos, memes, charts) unless the user explicitly wants to build a UI from them. Does NOT trigger on HTML source code, CSS, SVGs, or any code pasted as text.
10up-css
CSS architecture, best practices, and patterns for WordPress projects. Covers ITCSS methodology, accessibility, specificity management, naming conventions, and modern CSS features.
agentifind
This skill sets up codebase intelligence for AI agents by running the `agentifind` CLI to extract code structure and synthesize a `CODEBASE.md` navigation guide. It includes staleness detection and intelligently handles LSP installation for optimal accuracy.
CLAUDE.md – JJ Quick Command List
A concise cheat sheet for essential Jujutsu (`jj`) version control commands, designed to help AI agents or users quickly perform common repository operations.