Sourcegraph Code Search Skill

This skill enables autonomous code searching across repositories using the Sourcegraph CLI (src command).

When to Invoke This Skill

Use this skill when you need to:

• Research how features are implemented across codebases

• Find examples of API usage, patterns, or libraries

• Locate specific code patterns (functions, classes, imports)

• Analyze code across repositories (not just local files)

• Search commit history or diffs for changes

• Find security issues or credential leaks

• Understand architecture by searching for patterns

• Answer "where is X used?" questions across projects

Do NOT use for local file searches - use Grep/Glob instead.

Reference Navigation

The reference files are comprehensive. To find specific topics quickly:

Search reference.md sections

grep -n "^##" references/reference.md

Find specific filter documentation

grep -n "^### `repo:" references/reference.md grep -n "^### `file:" references/reference.md grep -n "^### `lang:" references/reference.md

Find examples by use case

grep -n "^##" references/examples.md

See reference.md for complete syntax documentation. See examples.md for practical search patterns organized by use case.

Quick Start

Basic Search Syntax

src search 'PATTERN' # Simple text search src search -json 'PATTERN' # JSON output for parsing src search 'repo:REGEX PATTERN' # Search specific repos src search 'lang:go PATTERN' # Search Go files only

Common Search Patterns

1. Find function/method implementations

src search 'lang:go func handleRequest' src search 'lang:python def authenticate'

2. Search in specific repository

src search 'repo:github.com/org/repo$ TODO' src search 'repo:sourcegraph/sourcegraph auth'

3. Search with multiple filters

src search 'repo:kubernetes lang:go file:test fmt.Errorf' src search 'TODO -file:test -file:spec'

See examples.md for more patterns including file types, commit history, and boolean operators.

Workflow

When searching code:

• Understand the goal - What pattern? Which repos/languages?

• Construct the query - Start with pattern, add filters (repo: , lang: , file: ), use operators (AND , OR , NOT )

• Execute - Run src search 'query' or src search -json 'query' for programmatic parsing

• Parse results - Extract matches, identify patterns, note files for investigation

• Refine - Too many results? Add filters. Too few? Broaden search.

Key Filters

Most common filters: repo: , lang: , file: , type: , case: , - prefix for exclusion.

See reference.md for complete filter documentation and syntax.

Pattern Types

Sourcegraph supports three pattern types:

Literal (default): Exact text matching

src search 'func main('

Regexp: Use patternType:regexp for regex (RE2 syntax)

src search 'patternType:regexp func \w+Handler'

Structural: Use patternType:structural for syntax-aware matching

src search 'patternType:structural fmt.Sprintf(:[format], :[...])'

See reference.md for complete pattern syntax, regex reference, and structural search details.

CLI Flags

• -json : Output results as JSON (for parsing)

• -stream : Stream results as they arrive

• -display N : Limit displayed results (with -stream )

: Separate flags from query (for queries starting with - )

Important Notes

Negation in Queries

Queries starting with negation need -- separator:

src search -- '-repo:foo/bar error'

Use -json for programmatic parsing. Set NO_COLOR=t to disable colors or COLOR=t to force colors when piping.

Default search scope excludes forks and archived repos. Include with fork:yes or archived:yes .

Examples by Use Case

Finding Implementation Examples

How do people handle authentication in Go?

src search 'lang:go repo:.auth. middleware'

React hooks usage

src search 'lang:typescript repo:facebook/react use.*Hook'

Security Auditing

Find hardcoded credentials

src search 'patternType:regexp (password|secret|api_key)\s*=\s*["'][^"']+["']'

Exposed private keys

src search 'type:diff BEGIN.*PRIVATE KEY'

API Research

How is this library used?

src search 'lang:python import requests'

Find all GraphQL mutations

src search 'file:.graphql$ type Mutation'

Refactoring Research

Find deprecated API usage

src search 'repo:myorg/ oldDeprecatedFunction'

Find TODO comments in non-test files

src search 'TODO -file:test -file:spec'

Advanced Features

For comprehensive syntax reference, pattern types, and advanced operators, see reference.md.

For more practical examples and complex query patterns, see examples.md.

Troubleshooting

No results?

• Check repository access/permissions

• Verify repository is indexed by Sourcegraph

• Try broader search terms

• Remove restrictive filters

Too many results?

• Add more specific filters

• Use lang: to narrow by language

• Use repo: with regex for specific repositories

• Combine with file: for specific paths

Syntax errors?

• Check regex syntax (RE2 format)

• Quote the entire query

• Use -- before queries starting with -

• Verify filter names are correct

Integration with Other Tools

After finding results with Sourcegraph:

• Use Read tool to examine specific files locally

• Use Grep for more detailed local searching

• Use Bash for git operations on repositories

• Use WebFetch to access repository URLs

Best Practices

• Start broad, then narrow: Begin with simple patterns, add filters incrementally

• Use appropriate pattern types: Literal for exact matches, regexp for patterns

• Combine filters effectively: repo:

• lang:
• file: for precision

• Parse JSON for programmatic analysis: Use -json when processing results

• Respect quotas and limits: Sourcegraph may have rate limits or result limits

• Cache insights: Remember patterns that work for future searches

Performance Tips

• Specific repo: filters are faster than broad searches

• Language filters (lang: ) significantly narrow scope

• File filters (file: ) reduce search surface

• Use count: to limit results when you just need examples

• Streaming (-stream ) is better for large result sets

Reference Files

• reference.md: Complete syntax documentation, all filters, operators, pattern types

• examples.md: Practical search patterns organized by use case