Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 26 additions & 26 deletions .claude/skills/searching-sourcegraph/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,25 +11,25 @@ Search before you build. Existing patterns reduce tokens, ensure consistency, an

**Start here:**

1. **Know the exact symbol or pattern?** → `sg_keyword_search`
2. **Know the concept, not the code?** → `sg_nls_search`
3. **Need to understand how/why?** → `sg_deepsearch_read`
4. **Tracing a symbol's usage?** → `sg_find_references`
5. **Need full implementation?** → `sg_go_to_definition` → `sg_read_file`
1. **Know the exact symbol or pattern?** → `mcp__sourcegraph__keyword_search`
2. **Know the concept, not the code?** → `mcp__sourcegraph__nls_search`
3. **Need to understand how/why?** → `mcp__sourcegraph__deepsearch_read`
4. **Tracing a symbol's usage?** → `mcp__sourcegraph__find_references`
5. **Need full implementation?** → `mcp__sourcegraph__go_to_definition` → `mcp__sourcegraph__read_file`

| Goal | Tool |
|------|------|
| Concepts/semantic search | `sg_nls_search` |
| Exact code patterns | `sg_keyword_search` |
| Trace usage | `sg_find_references` |
| See implementation | `sg_go_to_definition` |
| Understand systems | `sg_deepsearch_read` |
| Read files | `sg_read_file` |
| Browse structure | `sg_list_files` |
| Find repos | `sg_list_repos` |
| Search commits | `sg_commit_search` |
| Track changes | `sg_diff_search` |
| Compare versions | `sg_compare_revisions` |
| Concepts/semantic search | `mcp__sourcegraph__nls_search` |
| Exact code patterns | `mcp__sourcegraph__keyword_search` |
| Trace usage | `mcp__sourcegraph__find_references` |
| See implementation | `mcp__sourcegraph__go_to_definition` |
| Understand systems | `mcp__sourcegraph__deepsearch_read` |
| Read files | `mcp__sourcegraph__read_file` |
| Browse structure | `mcp__sourcegraph__list_files` |
| Find repos | `mcp__sourcegraph__list_repos` |
| Search commits | `mcp__sourcegraph__commit_search` |
| Track changes | `mcp__sourcegraph__diff_search` |
| Compare versions | `mcp__sourcegraph__compare_revisions` |

## Scoping (Always Do This)

Expand All @@ -53,8 +53,8 @@ Combine filters: `repo:^github.com/myorg/backend$ file:src/handlers lang:typescr
- Trace references if the error involves a known symbol

**When the user asks "how does X work":**
- Prefer `sg_deepsearch_read` for architectural understanding
- Follow up with `sg_read_file` on key files mentioned in the response
- Prefer `mcp__sourcegraph__deepsearch_read` for architectural understanding
- Follow up with `mcp__sourcegraph__read_file` on key files mentioned in the response

**When the user is implementing a new feature:**
- Search for similar existing implementations first
Expand All @@ -63,8 +63,8 @@ Combine filters: `repo:^github.com/myorg/backend$ file:src/handlers lang:typescr

**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 `sg_find_references`
- Check recent changes with `sg_diff_search` and `sg_commit_search` early — regressions are common
- Search for the error site, then trace the full call chain with `mcp__sourcegraph__find_references`
- Check recent changes with `mcp__sourcegraph__diff_search` and `mcp__sourcegraph__commit_search` early — regressions are common
- Find all affected code paths before writing the fix
- Read existing tests to understand intended behaviour

Expand All @@ -82,15 +82,15 @@ For detailed step-by-step workflows, see:
**Minimise tool calls:**
- Chain searches logically: search → read → references → definition
- Don't re-search for the same pattern; use results from prior calls
- Prefer `sg_keyword_search` over `sg_nls_search` when you have exact terms (faster, more precise)
- Prefer `mcp__sourcegraph__keyword_search` over `mcp__sourcegraph__nls_search` when you have exact terms (faster, more precise)

**Batch your understanding:**
- Read 2-3 related files before synthesising, rather than reading one and asking questions
- Use `sg_deepsearch_read` for "how does X work" instead of multiple keyword searches
- Use `mcp__sourcegraph__deepsearch_read` for "how does X work" instead of multiple keyword searches

**Avoid common token waste:**
- Don't search all repos when you know the target repo
- Don't use `sg_deepsearch_read` for simple "find all" queries
- Don't use `mcp__sourcegraph__deepsearch_read` for simple "find all" queries
- Don't re-read files you've already seen in this conversation

## Query Patterns
Expand Down Expand Up @@ -130,9 +130,9 @@ For more patterns, see `query-patterns.md`.
|---------|-----|
| Searching all repos | Add `repo:^github.com/org/repo$` |
| Too many results | Add `file:` pattern or keywords |
| Missing relevant code | Try `sg_nls_search` for semantic matching |
| Not understanding context | Use `sg_deepsearch_read` |
| Guessing patterns | Read implementations with `sg_read_file` |
| Missing relevant code | Try `mcp__sourcegraph__nls_search` for semantic matching |
| Not understanding context | Use `mcp__sourcegraph__deepsearch_read` |
| Guessing patterns | Read implementations with `mcp__sourcegraph__read_file` |

## Principles

Expand Down
24 changes: 12 additions & 12 deletions .claude/skills/searching-sourcegraph/examples/common-searches.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,64 +6,64 @@ Real-world search examples for common tasks.

**"Where is authentication handled?"**
```
sg_nls_search: "repo:^github.com/org/repo$ authentication middleware validation"
mcp__sourcegraph__nls_search: "repo:^github.com/org/repo$ authentication middleware validation"
```

**"How do we make API calls?"**
```
sg_keyword_search: "repo:^github.com/org/repo$ fetch\|axios\|http\.request"
mcp__sourcegraph__keyword_search: "repo:^github.com/org/repo$ fetch\|axios\|http\.request"
```

**"Find all database queries"**
```
sg_keyword_search: "repo:^github.com/org/repo$ \.query\(\|\.execute\("
mcp__sourcegraph__keyword_search: "repo:^github.com/org/repo$ \.query\(\|\.execute\("
```

## Understanding Flow

**"How does user signup work end-to-end?"**
```
sg_deepsearch_read: "Trace the user signup flow from form submission to database creation"
mcp__sourcegraph__deepsearch_read: "Trace the user signup flow from form submission to database creation"
```

**"What happens when a payment fails?"**
```
sg_deepsearch_read: "How does the system handle failed payment attempts?"
mcp__sourcegraph__deepsearch_read: "How does the system handle failed payment attempts?"
```

## Debugging

**"Find where this error is thrown"**
```
sg_keyword_search: "repo:^github.com/org/repo$ 'User not found'"
sg_find_references: Find all usages of the error constant
mcp__sourcegraph__keyword_search: "repo:^github.com/org/repo$ 'User not found'"
mcp__sourcegraph__find_references: Find all usages of the error constant
```

**"What changed in authentication recently?"**
```
sg_diff_search: repos=["github.com/org/repo"] pattern="auth" after="2 weeks ago"
mcp__sourcegraph__diff_search: repos=["github.com/org/repo"] pattern="auth" after="2 weeks ago"
```

## Finding Patterns

**"How do other features handle validation?"**
```
sg_nls_search: "repo:^github.com/org/repo$ input validation schema"
mcp__sourcegraph__nls_search: "repo:^github.com/org/repo$ input validation schema"
```

**"Find examples of pagination"**
```
sg_keyword_search: "repo:^github.com/org/repo$ offset\|limit\|cursor\|pageToken"
mcp__sourcegraph__keyword_search: "repo:^github.com/org/repo$ offset\|limit\|cursor\|pageToken"
```

## Tracing Dependencies

**"What uses this utility function?"**
```
sg_find_references: repo="github.com/org/repo" path="src/utils/format.ts" symbol="formatDate"
mcp__sourcegraph__find_references: repo="github.com/org/repo" path="src/utils/format.ts" symbol="formatDate"
```

**"Where is this type defined?"**
```
sg_go_to_definition: repo="github.com/org/repo" path="src/api/handler.ts" symbol="UserResponse"
mcp__sourcegraph__go_to_definition: repo="github.com/org/repo" path="src/api/handler.ts" symbol="UserResponse"
```
30 changes: 15 additions & 15 deletions .claude/skills/searching-sourcegraph/workflows/code-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,8 @@ Collect:
Check that the new code follows established conventions in the codebase:

```
sg_nls_search: "repo:^github.com/org/repo$ how is <concept> typically implemented"
sg_keyword_search: "repo:^github.com/org/repo$ file:src/<area>/ <pattern or function name>"
mcp__sourcegraph__nls_search: "repo:^github.com/org/repo$ how is <concept> typically implemented"
mcp__sourcegraph__keyword_search: "repo:^github.com/org/repo$ file:src/<area>/ <pattern or function name>"
```

Look for:
Expand All @@ -43,16 +43,16 @@ Look for:
- Whether shared utilities exist that should be reused

```
sg_read_file: <2-3 representative files from the same area>
mcp__sourcegraph__read_file: <2-3 representative files from the same area>
```

### 3. Search for Prior Art on the Same Problem

Confirm the approach isn't reinventing something already solved:

```
sg_nls_search: "repo:^github.com/org/repo$ <feature or problem the PR solves>"
sg_commit_search: repos=["org/repo"] messageTerms=["<keyword related to the change>"]
mcp__sourcegraph__nls_search: "repo:^github.com/org/repo$ <feature or problem the PR solves>"
mcp__sourcegraph__commit_search: repos=["org/repo"] messageTerms=["<keyword related to the change>"]
```

If a similar feature exists, compare the approaches and flag divergence if it reduces consistency.
Expand All @@ -62,7 +62,7 @@ If a similar feature exists, compare the approaches and flag divergence if it re
For any modified public symbol (function, type, constant), check its usage:

```
sg_find_references: <modified function or type>
mcp__sourcegraph__find_references: <modified function or type>
```

Verify:
Expand All @@ -73,16 +73,16 @@ Verify:
For deeper impact analysis:

```
sg_deepsearch_read: "How is <changed component> used across the system?"
mcp__sourcegraph__deepsearch_read: "How is <changed component> used across the system?"
```

### 5. Review Test Coverage

Read the existing tests for the affected area:

```
sg_keyword_search: "repo:^github.com/org/repo$ file:.*\.test\. <function or module name>"
sg_read_file: <relevant test files>
mcp__sourcegraph__keyword_search: "repo:^github.com/org/repo$ file:.*\.test\. <function or module name>"
mcp__sourcegraph__read_file: <relevant test files>
```

Check:
Expand All @@ -96,14 +96,14 @@ Check:
Recent activity reveals context and potential conflicts:

```
sg_diff_search: "repo:^github.com/org/repo$ <file path or function name>"
sg_commit_search: repos=["org/repo"] messageTerms=["<area keyword>"]
mcp__sourcegraph__diff_search: "repo:^github.com/org/repo$ <file path or function name>"
mcp__sourcegraph__commit_search: repos=["org/repo"] messageTerms=["<area keyword>"]
```

Use `sg_compare_revisions` to see what changed in the area recently:
Use `mcp__sourcegraph__compare_revisions` to see what changed in the area recently:

```
sg_compare_revisions: repo="org/repo" base="main~30" head="main" path="src/<affected area>/"
mcp__sourcegraph__compare_revisions: repo="org/repo" base="main~30" head="main" path="src/<affected area>/"
```

Look for:
Expand All @@ -124,8 +124,8 @@ After searching, compile review comments around:
## Tips

- Search before commenting — many apparent issues are intentional deviations with prior art
- Use `sg_find_references` before flagging a changed signature as breaking; verify actual impact
- Use `mcp__sourcegraph__find_references` before flagging a changed signature as breaking; verify actual impact
- Read tests first — they often clarify the intended contract faster than the implementation
- Check recent commits in the same path; the PR may be part of a larger sequence of changes
- Use `sg_deepsearch_read` when the change touches a system you're unfamiliar with before reviewing it
- Use `mcp__sourcegraph__deepsearch_read` when the change touches a system you're unfamiliar with before reviewing it
- Scope searches to the affected directory or module to reduce noise
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Task Progress:
### 1. Search for the Error

```
sg_keyword_search: "repo:X 'INVALID_TOKEN_ERROR'"
mcp__sourcegraph__keyword_search: "repo:X 'INVALID_TOKEN_ERROR'"
```

Search for:
Expand All @@ -29,7 +29,7 @@ Search for:
### 2. Find Where It's Thrown

```
sg_find_references: Trace the error symbol
mcp__sourcegraph__find_references: Trace the error symbol
```

Locate all places this error can originate:
Expand All @@ -40,7 +40,7 @@ Locate all places this error can originate:
### 3. Understand the Context

```
sg_deepsearch_read: "When is INVALID_TOKEN_ERROR thrown and how should it be handled?"
mcp__sourcegraph__deepsearch_read: "When is INVALID_TOKEN_ERROR thrown and how should it be handled?"
```

Get deeper understanding of:
Expand All @@ -51,8 +51,8 @@ Get deeper understanding of:
### 4. Check Recent Changes

```
sg_diff_search: "repo:X INVALID_TOKEN_ERROR"
sg_commit_search: repos=["X"] messageTerms=["token", "auth"]
mcp__sourcegraph__diff_search: "repo:X INVALID_TOKEN_ERROR"
mcp__sourcegraph__commit_search: repos=["X"] messageTerms=["token", "auth"]
```

Look for recent modifications that might have introduced the bug.
Expand Down
Loading