How this skill is triggered — by the user, by Claude, or both
Slash command
/soda-gql-skills:gql-inspectThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill analyzes GraphQL fragments and operations in your soda-gql project using the `soda-gql-lsp-cli` tool. It provides symbol listings, diagnostics, and type context for any file or symbol.
This skill analyzes GraphQL fragments and operations in your soda-gql project using the soda-gql-lsp-cli tool. It provides symbol listings, diagnostics, and type context for any file or symbol.
First, detect the soda-gql project configuration:
!bun ${CLAUDE_PLUGIN_ROOT}/scripts/detect-project.ts
The output includes:
found: Whether a soda-gql project was detectedconfigPath: Path to the config fileschemas: Schema names and their file pathsoutdir: Output directory for generated fileshasLsp: Whether LSP is availableIf hasLsp: false, inform the user:
The
gql:inspectskill requires@soda-gql/lspand@soda-gql/protocol-proxyto be installed. Please add them to your project dependencies and runbun install.
Exit the skill.
Parse $ARGUMENTS to determine the input mode. There are three modes:
If the argument contains / or ends in .ts or .tsx, treat it as a file path and use it directly.
If the argument looks like an identifier (letters, digits, underscores, no path separators, no spaces), treat it as a symbol name:
**/*.{ts,tsx}soda-gql-lsp-cli symbols <file>
name matches the argument.Important: Do NOT use the --workspace flag (DD-7 constraint). Freeform resolution must use Glob/Grep to find candidate files.
If the argument is empty or looks like a question (contains spaces, ends with ?), use AskUserQuestion:
Question: "What would you like to inspect?"
Options:
**/*.{ts,tsx} and run symbols on each file that contains GraphQL definitionsRun the symbols subcommand on the resolved file:
soda-gql-lsp-cli symbols <file>
Expected output: JSON array with objects:
[
{ "name": "UserFragment", "kind": "fragment", "typeName": "User", "schemaName": "default", "line": 5 },
{ "name": "GetUserQuery", "kind": "query", "variables": [{ "name": "id", "type": "ID!" }], "schemaName": "default", "line": 20 }
]
If no symbols found: Inform the user that the file has no GraphQL definitions recognized by soda-gql. Suggest checking that the file uses gql.default(...) or similar builder patterns.
Present as a table:
| Name | Kind | Type / Variables | Schema | Line |
|---|---|---|---|---|
| UserFragment | fragment | User | default | 5 |
| GetUserQuery | query | id: ID! | default | 20 |
Run the diagnostics subcommand on the same file:
soda-gql-lsp-cli diagnostics <file>
Expected output: JSON array:
[
{ "message": "Field 'userName' does not exist on type 'User'", "line": 8, "column": 5, "severity": "error" },
{ "message": "Fragment 'OldFragment' is unused", "line": 22, "column": 1, "severity": "warning" }
]
If empty array: Report "No issues found — file is clean."
If non-empty: Group and present by severity:
Errors (1):
Line 8, col 5: Field 'userName' does not exist on type 'User'
Warnings (1):
Line 22, col 1: Fragment 'OldFragment' is unused
Fetch type information when:
Run the schema subcommand:
soda-gql-lsp-cli schema <typeName>
For projects with multiple schemas, pass the schema name from detect-project's schemas keys:
soda-gql-lsp-cli schema <typeName> --schema <schemaName>
Output varies by kind:
Present the type information in a structured format relevant to the kind.
Provide a consolidated view in this order:
List all GraphQL definitions found in the file (from step 4).
<filename>."Include type details when fetched (from step 6), labeled clearly.
Suggest relevant follow-up actions based on the results:
gql:doctor for project-wide health checks."gql:scaffold to add a new fragment or operation to this file."bun run soda-gql codegen schema to regenerate types."gql:guide for syntax reference and examples."Error: Command not found: soda-gql-lsp-cli
Fix suggestion:
Install
@soda-gql/protocol-proxyglobally or ensure it's in your project dependencies:bun add -d @soda-gql/protocol-proxyThen verify the binary is available:
bun run node_modules/.bin/soda-gql-lsp-cli --help
Error: No such file or directory: <path>
Fix suggestion:
Check that the file path is correct. Use Glob to search for the file:
Glob **/<filename>.{ts,tsx}
If soda-gql-lsp-cli symbols <file> returns an empty array:
No GraphQL definitions were found in
<file>. Ensure the file uses soda-gql builder patterns such asgql.default(({ fragment }) => fragment("Name", "Type")\{ ... }`())`.
If soda-gql-lsp-cli exits with a non-zero code:
bun ${CLAUDE_PLUGIN_ROOT}/scripts/detect-project.ts
bun run soda-gql codegen schema
User: gql:inspect src/graphql/fragments.ts
Process:
hasLsp: true/ → Mode A (file path)soda-gql-lsp-cli symbols src/graphql/fragments.ts → 3 fragments foundsoda-gql-lsp-cli diagnostics src/graphql/fragments.ts → 1 warningUser: gql:inspect UserFragment
Process:
hasLsp: true**/*.{ts,tsx} → find candidate filessoda-gql-lsp-cli symbols on each candidateUserFragment symbolUser: gql:inspect
Process:
hasLsp: trueBefore completing this skill, ensure:
hasLsp: truesoda-gql-lsp-cli symbols was executed and results were presented as a tablesoda-gql-lsp-cli diagnostics was executed and results were summarizedsoda-gql-lsp-cli schema when relevantnpx claudepluginhub whatasoda/soda-gql-skills --plugin soda-gql-skillsRuns a 7-phase codebase analysis using typegraph-mcp tools, producing a detailed architectural report. Useful when onboarding to an unfamiliar codebase or before making significant changes.
Provides Go repository intelligence via AST-accurate call graphs, blast radius analysis, and 57+ semantic queries. Replaces grep for Go symbol navigation, editing, refactoring, and bug hunting.
Explores codebases using SocratiCode semantic search, dependency graphs, and tools like codebase_search for understanding architecture, finding functions/types, analyzing dependencies, and searching schemas/specs.