Searching Sourcegraph
Wire Sourcegraph-backed code search into your agent workflow before implementing features or while debugging unfamiliar repos.
Overview
Searching Sourcegraph is an agent skill most often used in Build › Integrations (also Idea › Research and Ship › Testing) that routes implementation, debugging, and system-understanding questions through scoped Sourcegra
Install
npx skills add https://github.com/sourcegraph-community/sourcegraph-skill --skill searching-sourcegraphWhat is this skill?
- 6-step tool-selection flow: exact symbol → NLS → deepsearch → references → definition → contributor repos
- Goal-to-tool table covering nls_search, keyword_search, find_references, go_to_definition, deepsearch/deepsearch_read, a
- Mandatory repo scoping patterns (exact repo, org prefix, file regex) to keep agent queries precise
- Commit, diff, compare_revisions, and get_contributor_repos paths for change tracing and ownership context
- Search-before-build discipline to reuse proven patterns and reduce speculative implementation tokens
- 6-step numbered tool-selection flow at the top of the skill
- 13+ named Sourcegraph tools in the goal-to-tool reference table
Adoption & trust: 1 installs on skills.sh; 12 GitHub stars; 2/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
You need to implement or debug behavior in repos you do not fully know, and ad-hoc local search or guesswork wastes time and agent tokens.
Who is it for?
Solo builders working in Sourcegraph-indexed org repos who want a repeatable search ritual before coding or while tracing symbols and commits.
Skip if: Greenfield experiments with no indexed upstream to search, or teams without Sourcegraph access who only need single-repo local grep.
When should I use this skill?
Implementation questions, debugging, or “how does X work” queries against Sourcegraph-indexed codebases.
What do I get? / Deliverables
Your agent picks the right Sourcegraph tool chain, scopes queries to the correct repos, and returns patterns, definitions, and references you can implement or fix against confidently.
- Scoped search results (keyword, NLS, or deepsearch summaries)
- Symbol traces via find_references and go_to_definition with targeted read_file excerpts
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build because the skill’s core promise is “search before you build” and tool routing for implementation patterns in indexed codebases. Integrations fits best: it teaches how to invoke Sourcegraph search, navigation, and repo-scoping tools rather than shipping product UI or backend code directly.
Where it fits
Run nls_search scoped to a competitor’s open-source mirror to see how they structure auth before you commit to your own design.
Keyword-search for an existing webhook handler pattern in `repo:^github.com/ORG/API$` and go_to_definition before adding a new endpoint.
Use find_references on a shared DTO to match error-handling conventions across services you are extending.
Deepsearch plus read_file on the failing module path, then diff_search recent commits when a regression does not reproduce locally.
Compare revisions and commit_search to see when a feature flag or config default changed after an incident report.
How it compares
Use this procedural skill to orchestrate Sourcegraph code intelligence—not as a substitute for unstructured chat guesses or a generic filesystem-only search skill.
Common Questions / FAQ
Who is searching-sourcegraph for?
It is for solo and indie builders using AI coding agents who need to query large, org-scale codebases indexed in Sourcegraph before implementing or while debugging.
When should I use searching-sourcegraph?
Use it during Build when you need existing patterns before writing code; during Ship › Testing when debugging unfamiliar modules; and during Idea › Research when answering “how does X work” across repos—always with explicit repo scoping.
Is searching-sourcegraph safe to install?
Review the Security Audits panel on this Prism page for ingest-time signals; the skill implies network and API access to Sourcegraph—confirm org policies and credentials before enabling it in production agents.
SKILL.md
READMESKILL.md - Searching Sourcegraph
# Searching Sourcegraph Search before you build. Existing patterns reduce tokens, ensure consistency, and surface tested solutions. ## Tool Selection Logic **Start here:** 1. **Know the exact symbol or pattern?** → `keyword_search` 2. **Know the concept, not the code?** → `nls_search` 3. **Need to understand how/why?** → `deepsearch` → `deepsearch_read` 4. **Tracing a symbol's usage?** → `find_references` 5. **Need full implementation?** → `go_to_definition` → `read_file` 6. **Need to know what repos a user has worked on?** → `get_contributor_repos` | Goal | Tool | |------|------| | Concepts/semantic search | `nls_search` | | Exact code patterns | `keyword_search` | | Trace usage | `find_references` | | See implementation | `go_to_definition` | | Initiate a deep search | `deepsearch` | | Read deep search results | `deepsearch_read` | | Read files | `read_file` | | Browse structure | `list_files` | | Find repos | `list_repos` | | Search commits | `commit_search` | | Track changes | `diff_search` | | Compare versions | `compare_revisions` | | Find repos a user has worked on | `get_contributor_repos` | ## Scoping (Always Do This) ``` repo:^github.com/ORG/REPO$ # Exact repo (preferred) repo:github.com/ORG/ # All repos in org file:.*\.ts$ # TypeScript only file:src/api/ # Specific directory file:.*\.test\.ts$ -file:__mocks__ # Tests, exclude mocks ``` Start narrow. Expand only if results are empty. Combine filters: `repo:^github.com/myorg/backend$ file:src/handlers lang:typescript` ## Context-Aware Behaviour **When the user provides a file path or error message:** - Extract symbols, function names, or error codes - Search for those exact terms first - Trace references if the error involves a known symbol **When the user asks "how does X work":** - Use `deepsearch` to initiate the search, then `deepsearch_read` to retrieve results - Follow up with `read_file` on key files mentioned in the response **When the user asks who worked on something or what repos a contributor has touched:** - Use `get_contributor_repos` with one or more usernames to discover their active repositories - Then scope subsequent searches to those repos **When the user is implementing a new feature:** - Search for similar existing implementations first - Read tests for usage examples - Check for shared utilities before creating new ones **When troubleshooting an error, build failure, or runtime exception:** - Extract exact symbols, error codes, or log lines from the stack trace or build output - Search for the error site, then trace the full call chain with `find_references` - Check recent changes with `diff_search` and `commit_search` early — regressions are common - Identify all affected code paths and services before proposing a fix **When fixing a bug:** - Extract exact symbols from the error message or stack trace - Search for the error site, then trace the full call chain with `find_references` - Check recent changes with `diff_search` and `commit_search` early — regressions are common - Find all affected code paths before writing the fix - Read existing tests to understand intended behaviour ## Workflows For detailed step-by-step workflows, see: - `workflows/implementing-feature.md` — when building new features - `workflows/understanding-code.md` — when exploring unfamiliar systems - `workflows/debugging-issue.md` — when troubleshooting errors, build failures, stack traces, support issues, or runtime exceptions - `workflows/fixing-bug.md` — when fixing bugs with extensive Sourcegraph search - `workflows/code-review.md` — when reviewing a pull request or changeset ## Efficiency Rules **Minimise tool calls:** - Chain searches logically: search → read →