From fc23315c175eb31d80ec1fb8b49834288822beb2 Mon Sep 17 00:00:00 2001 From: Jack Yin Date: Thu, 12 Mar 2026 11:51:10 -0400 Subject: [PATCH] fix: update tool names to match Claude Code MCP naming convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Claude Code names MCP tools as `mcp____` based on how the server is registered (e.g. `claude mcp add sourcegraph ` produces `mcp__sourcegraph__keyword_search`). The `sg_*` shorthand names used in this skill don't match any valid Claude Code MCP registration name — they silently fail with no error, making the skill non-functional. This PR renames all `sg_*` tool references to `mcp__sourcegraph__*` to match the standard Claude Code convention when the Sourcegraph MCP server is registered under the name "sourcegraph". Reported by CoreWeave while vendoring this skill into their internal Claude Code plugin marketplace. --- .claude/skills/searching-sourcegraph/SKILL.md | 52 +++++++++---------- .../examples/common-searches.md | 24 ++++----- .../workflows/code-review.md | 30 +++++------ .../workflows/debugging-issue.md | 10 ++-- .../workflows/fixing-bug.md | 42 +++++++-------- .../workflows/implementing-feature.md | 8 +-- .../workflows/understanding-code.md | 10 ++-- 7 files changed, 88 insertions(+), 88 deletions(-) diff --git a/.claude/skills/searching-sourcegraph/SKILL.md b/.claude/skills/searching-sourcegraph/SKILL.md index 3846aba..fce5c69 100644 --- a/.claude/skills/searching-sourcegraph/SKILL.md +++ b/.claude/skills/searching-sourcegraph/SKILL.md @@ -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) @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/.claude/skills/searching-sourcegraph/examples/common-searches.md b/.claude/skills/searching-sourcegraph/examples/common-searches.md index c0f080d..98d0105 100644 --- a/.claude/skills/searching-sourcegraph/examples/common-searches.md +++ b/.claude/skills/searching-sourcegraph/examples/common-searches.md @@ -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" ``` diff --git a/.claude/skills/searching-sourcegraph/workflows/code-review.md b/.claude/skills/searching-sourcegraph/workflows/code-review.md index 485d239..08bb7e0 100644 --- a/.claude/skills/searching-sourcegraph/workflows/code-review.md +++ b/.claude/skills/searching-sourcegraph/workflows/code-review.md @@ -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 typically implemented" -sg_keyword_search: "repo:^github.com/org/repo$ file:src// " +mcp__sourcegraph__nls_search: "repo:^github.com/org/repo$ how is typically implemented" +mcp__sourcegraph__keyword_search: "repo:^github.com/org/repo$ file:src// " ``` Look for: @@ -43,7 +43,7 @@ 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 @@ -51,8 +51,8 @@ sg_read_file: <2-3 representative files from the same area> Confirm the approach isn't reinventing something already solved: ``` -sg_nls_search: "repo:^github.com/org/repo$ " -sg_commit_search: repos=["org/repo"] messageTerms=[""] +mcp__sourcegraph__nls_search: "repo:^github.com/org/repo$ " +mcp__sourcegraph__commit_search: repos=["org/repo"] messageTerms=[""] ``` If a similar feature exists, compare the approaches and flag divergence if it reduces consistency. @@ -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: +mcp__sourcegraph__find_references: ``` Verify: @@ -73,7 +73,7 @@ Verify: For deeper impact analysis: ``` -sg_deepsearch_read: "How is used across the system?" +mcp__sourcegraph__deepsearch_read: "How is used across the system?" ``` ### 5. Review Test Coverage @@ -81,8 +81,8 @@ sg_deepsearch_read: "How is used across the system?" Read the existing tests for the affected area: ``` -sg_keyword_search: "repo:^github.com/org/repo$ file:.*\.test\. " -sg_read_file: +mcp__sourcegraph__keyword_search: "repo:^github.com/org/repo$ file:.*\.test\. " +mcp__sourcegraph__read_file: ``` Check: @@ -96,14 +96,14 @@ Check: Recent activity reveals context and potential conflicts: ``` -sg_diff_search: "repo:^github.com/org/repo$ " -sg_commit_search: repos=["org/repo"] messageTerms=[""] +mcp__sourcegraph__diff_search: "repo:^github.com/org/repo$ " +mcp__sourcegraph__commit_search: repos=["org/repo"] messageTerms=[""] ``` -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//" +mcp__sourcegraph__compare_revisions: repo="org/repo" base="main~30" head="main" path="src//" ``` Look for: @@ -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 diff --git a/.claude/skills/searching-sourcegraph/workflows/debugging-issue.md b/.claude/skills/searching-sourcegraph/workflows/debugging-issue.md index 56548eb..1bf3baf 100644 --- a/.claude/skills/searching-sourcegraph/workflows/debugging-issue.md +++ b/.claude/skills/searching-sourcegraph/workflows/debugging-issue.md @@ -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: @@ -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: @@ -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: @@ -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. diff --git a/.claude/skills/searching-sourcegraph/workflows/fixing-bug.md b/.claude/skills/searching-sourcegraph/workflows/fixing-bug.md index cb5bbed..2bcaed0 100644 --- a/.claude/skills/searching-sourcegraph/workflows/fixing-bug.md +++ b/.claude/skills/searching-sourcegraph/workflows/fixing-bug.md @@ -30,7 +30,7 @@ The more precise your search terms, the fewer tool calls you need. ### 2. Search for the Error Site ``` -sg_keyword_search: "repo:^github.com/org/repo$ 'ExactErrorMessageHere'" +mcp__sourcegraph__keyword_search: "repo:^github.com/org/repo$ 'ExactErrorMessageHere'" ``` Also search for: @@ -39,8 +39,8 @@ Also search for: - Log statement nearest the failure ``` -sg_keyword_search: "repo:X file:src/ ErrTokenExpired" -sg_nls_search: "repo:X token validation failure handling" +mcp__sourcegraph__keyword_search: "repo:X file:src/ ErrTokenExpired" +mcp__sourcegraph__nls_search: "repo:X token validation failure handling" ``` Run multiple searches in parallel when you have several candidate terms. @@ -48,7 +48,7 @@ Run multiple searches in parallel when you have several candidate terms. ### 3. Find Where the Error Originates ``` -sg_find_references: +mcp__sourcegraph__find_references: ``` Locate every site that can produce this error: @@ -56,20 +56,20 @@ Locate every site that can produce this error: - Error factory functions - Middleware or interceptors that wrap errors -Read each throw site with `sg_read_file` to understand the exact condition. +Read each throw site with `mcp__sourcegraph__read_file` to understand the exact condition. ### 4. Trace the Full Call Chain ``` -sg_go_to_definition: -sg_find_references: +mcp__sourcegraph__go_to_definition: +mcp__sourcegraph__find_references: ``` Walk the chain upward until you reach the entry point (HTTP handler, queue consumer, CLI command, etc.). For complex chains, use: ``` -sg_deepsearch_read: "How does the X flow work from entry point to error site?" +mcp__sourcegraph__deepsearch_read: "How does the X flow work from entry point to error site?" ``` ### 5. Find All Affected Code Paths @@ -77,8 +77,8 @@ sg_deepsearch_read: "How does the X flow work from entry point to error site?" Bugs often affect more than one path. Search broadly: ``` -sg_keyword_search: "repo:X " -sg_find_references: +mcp__sourcegraph__keyword_search: "repo:X " +mcp__sourcegraph__find_references: ``` Confirm whether: @@ -91,13 +91,13 @@ Confirm whether: Recent commits are the most common source of regressions: ``` -sg_diff_search: "repo:X " -sg_commit_search: repos=["org/repo"] messageTerms=["keyword related to bug area"] +mcp__sourcegraph__diff_search: "repo:X " +mcp__sourcegraph__commit_search: repos=["org/repo"] messageTerms=["keyword related to bug area"] ``` -Use `sg_compare_revisions` if you want to diff a specific before/after window: +Use `mcp__sourcegraph__compare_revisions` if you want to diff a specific before/after window: ``` -sg_compare_revisions: repo="org/repo" base="main~30" head="main" path="src/auth/" +mcp__sourcegraph__compare_revisions: repo="org/repo" base="main~30" head="main" path="src/auth/" ``` ### 7. Understand the Intended Behaviour @@ -105,8 +105,8 @@ sg_compare_revisions: repo="org/repo" base="main~30" head="main" path="src/auth/ Before writing the fix, confirm what correct behaviour looks like: ``` -sg_nls_search: "repo:X how should behave when " -sg_read_file: +mcp__sourcegraph__nls_search: "repo:X how should behave when " +mcp__sourcegraph__read_file: ``` Read existing tests to understand invariants. If tests are missing, that is part of the bug. @@ -116,8 +116,8 @@ Read existing tests to understand invariants. If tests are missing, that is part Search for similar bugs that were already fixed in the codebase: ``` -sg_commit_search: repos=["org/repo"] messageTerms=["fix", "bug keyword"] -sg_nls_search: "repo:X handle " +mcp__sourcegraph__commit_search: repos=["org/repo"] messageTerms=["fix", "bug keyword"] +mcp__sourcegraph__nls_search: "repo:X handle " ``` Match your fix to the established pattern so it stays consistent with the codebase. @@ -125,8 +125,8 @@ Match your fix to the established pattern so it stays consistent with the codeba ## Tips - Search extensively before writing a single line of code — most fix time should be spent understanding, not coding -- Never assume the first throw site is the only one; always use `sg_find_references` +- Never assume the first throw site is the only one; always use `mcp__sourcegraph__find_references` - Check tests first: a failing test often tells you more than the code does - Recent diffs narrow suspects dramatically — check them early -- If `sg_keyword_search` returns too many results, scope with `file:` or `lang:` filters -- Use `sg_deepsearch_read` when the bug spans multiple layers and you need architectural context +- If `mcp__sourcegraph__keyword_search` returns too many results, scope with `file:` or `lang:` filters +- Use `mcp__sourcegraph__deepsearch_read` when the bug spans multiple layers and you need architectural context diff --git a/.claude/skills/searching-sourcegraph/workflows/implementing-feature.md b/.claude/skills/searching-sourcegraph/workflows/implementing-feature.md index 5bb1d7e..a074328 100644 --- a/.claude/skills/searching-sourcegraph/workflows/implementing-feature.md +++ b/.claude/skills/searching-sourcegraph/workflows/implementing-feature.md @@ -17,7 +17,7 @@ Task Progress: ### 1. Find Similar Implementations ``` -sg_nls_search: "repo:^github.com/org/repo$ user settings CRUD" +mcp__sourcegraph__nls_search: "repo:^github.com/org/repo$ user settings CRUD" ``` Look for features that solve similar problems. Note the patterns used. @@ -25,7 +25,7 @@ Look for features that solve similar problems. Note the patterns used. ### 2. Explore File Structure ``` -sg_keyword_search: "repo:^github.com/org/repo$ file:src/features/ index.ts" +mcp__sourcegraph__keyword_search: "repo:^github.com/org/repo$ file:src/features/ index.ts" ``` Understand how features are organised in this codebase. @@ -33,7 +33,7 @@ Understand how features are organised in this codebase. ### 3. Study a Representative Example ``` -sg_read_file: Read 2-3 files from a well-implemented similar feature +mcp__sourcegraph__read_file: Read 2-3 files from a well-implemented similar feature ``` Pay attention to: @@ -45,7 +45,7 @@ Pay attention to: ### 4. Check for Shared Utilities ``` -sg_find_references: Trace usage of common utilities +mcp__sourcegraph__find_references: Trace usage of common utilities ``` Before creating new helpers, check if reusable utilities exist: diff --git a/.claude/skills/searching-sourcegraph/workflows/understanding-code.md b/.claude/skills/searching-sourcegraph/workflows/understanding-code.md index 18213e0..56e0163 100644 --- a/.claude/skills/searching-sourcegraph/workflows/understanding-code.md +++ b/.claude/skills/searching-sourcegraph/workflows/understanding-code.md @@ -17,7 +17,7 @@ Task Progress: ### 1. Get the Big Picture ``` -sg_deepsearch_read: "How does order fulfillment work in this codebase?" +mcp__sourcegraph__deepsearch_read: "How does order fulfillment work in this codebase?" ``` Deep Search provides architectural understanding. Ask "how" and "why" questions. @@ -25,7 +25,7 @@ Deep Search provides architectural understanding. Ask "how" and "why" questions. ### 2. Find Entry Points ``` -sg_keyword_search: "repo:X file:src/routes export.*order" +mcp__sourcegraph__keyword_search: "repo:X file:src/routes export.*order" ``` Look for: @@ -37,8 +37,8 @@ Look for: ### 3. Trace the Implementation ``` -sg_go_to_definition: Jump to main handler -sg_find_references: See how it's used +mcp__sourcegraph__go_to_definition: Jump to main handler +mcp__sourcegraph__find_references: See how it's used ``` Follow the code path from entry point through business logic. @@ -46,7 +46,7 @@ Follow the code path from entry point through business logic. ### 4. Review Related Tests ``` -sg_keyword_search: "repo:X file:.*\.test\.ts describe.*order" +mcp__sourcegraph__keyword_search: "repo:X file:.*\.test\.ts describe.*order" ``` Tests reveal: