codebase-navigator_skill

Overview

This skill provides semantic code search using osgrep to help you locate implementations, understand architecture, and navigate large projects by meaning rather than exact text. It surfaces relevant files and snippets, suggests focused queries, and guides how to synthesize findings into clear answers. Use it whenever you need to find where a behavior is implemented or how a component works across a codebase.

How this skill works

It checks or refreshes an osgrep index for the repository, runs natural-language queries against the indexed content, and returns ranked matches with file paths and snippet previews. The workflow recommends inspecting the returned snippets, reading the surrounding code for context, and producing a concise explanation that cites files and line ranges. It supports modes for compact file lists, full content, relevance scores, and machine-readable JSON.

When to use it

• Asking “where is X implemented?” or “how does Y work?”
• Finding code that handles a specific feature, workflow, or behavior
• Exploring architecture and implementation patterns across a large repo
• Locating API endpoints, config loading, or database queries
• Refining vague searches into actionable file-level pointers

Best practices

• Use descriptive natural-language phrases instead of single keywords (e.g., “authentication logic and user login”).
• Refresh the osgrep index when the repo has changed or results look stale (use --sync for safety).
• Start broad, then narrow queries with domain terms and synonyms if results are noisy.
• Prefer --compact for quick file overviews and --content when you need full context.
• Always read matched snippets in context and cite files + line ranges rather than dumping raw search output.

Example use cases

• User: “Where do we calculate shipping costs?” → query: “shipping cost calculation and pricing logic”; result: files and lines to inspect.
• User: “How does authentication work?” → find login, session, and middleware implementations and summarize flow.
• User: “Find the code that handles config loading” → search descriptive phrase, then cite loader and env parsing files.
• Refactor planning: locate all uses of a pattern (e.g., “cache invalidation and TTL”) to estimate impact.
• Automated tooling: run osgrep --json to feed search results into a remediation or analysis script.