How this skill is triggered — by the user, by Claude, or both
Slash command
/soda-gql-skills:gql-doctorThis 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 runs comprehensive diagnostics on your soda-gql project using the `soda-gql doctor` command and additional extended checks.
This skill runs comprehensive diagnostics on your soda-gql project using the soda-gql doctor command and additional extended checks.
First, detect the soda-gql project configuration:
!bun ${CLAUDE_PLUGIN_ROOT}/scripts/detect-project.ts
The output will include:
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 found: false, inform the user:
No soda-gql project detected in the current directory. Make sure you have a
soda-gql.config.{ts,js,mjs}file and have runbun installto install dependencies.
Exit the skill.
Execute the doctor command:
bun run soda-gql doctor
Expected output:
The doctor command performs 4 core checks:
@soda-gql/* packages have matching versionsFor each check, present the status and actionable fix suggestions:
What it checks:
@soda-gql/* packages in package.json have the same versionOn failure:
❌ version-consistency: Found version mismatches
@soda-gql/core: 0.2.0
@soda-gql/builder: 0.1.5
Fix suggestion:
@soda-gql/* packages to the same versionbun install to sync lockfilebun add @soda-gql/core@latest @soda-gql/builder@latest [other packages]
Auto-fix offer: Use AskUserQuestion to ask: "Would you like me to update all @soda-gql packages to the latest matching version?"
What it checks:
On failure:
❌ duplicate-packages: Found duplicates
@soda-gql/core appears at:
- node_modules/@soda-gql/core
- node_modules/@soda-gql/builder/node_modules/@soda-gql/core
Fix suggestion:
rm -rf node_modules
bun install
.npmrc for hoist settingsAuto-fix offer: Use AskUserQuestion to ask: "Would you like me to remove node_modules and reinstall dependencies with Bun?"
What it checks:
outdir, schemasOn failure:
❌ config-validation: Invalid config structure
Missing required field: outdir
Fix suggestion:
outdir or schemas fieldexport default)import { defineConfig } from '@soda-gql/config';
export default defineConfig({
outdir: './src/graphql/generated',
schemas: {
default: {
schemaFiles: ['./schema.graphql'],
},
},
});
Auto-fix offer: Use AskUserQuestion to ask: "Would you like me to inspect and fix the config file structure?"
What it checks:
outdir are up-to-date with schema filesOn failure:
❌ codegen-freshness: Generated files are stale
Schema modified: 2026-02-17 10:30:00
Last codegen: 2026-02-17 09:15:00
Fix suggestion:
bun run soda-gql codegen schema
Auto-fix offer: Use AskUserQuestion to ask: "Would you like me to run codegen to update generated files?"
After core diagnostics, run additional validation checks:
bun run soda-gql typegen
What it checks:
On failure:
Error: Field 'userName' does not exist on type 'User'
at src/graphql/operations.ts:10:5
Fix suggestion:
Auto-fix offer: If the error is a simple typo or field name mismatch, use AskUserQuestion: "Would you like me to fix this field name?"
Conditional: Only run this check when
hasLsp: truefrom detect-project output AND typegen reported errors for specific files.
When typegen (Extended Check 1) reports errors referencing specific source files, run soda-gql-lsp-cli diagnostics on each affected file to get pinpoint field-level diagnostics with exact line and column locations.
For single-schema projects:
soda-gql-lsp-cli diagnostics <file>
For multi-schema projects (pass --schema <name> based on detect-project schemas):
soda-gql-lsp-cli diagnostics <file> --schema <schemaName>
Output format (JSON array):
[
{
"message": "Field 'userName' does not exist on type 'User'",
"line": 10,
"column": 5,
"severity": "Error"
}
]
Severity values: "Error", "Warning", "Information", "Hint"
Presenting results:
src/graphql/operations.ts
Line 10, Col 5 [Error]: Field 'userName' does not exist on type 'User'
Line 24, Col 3 [Warning]: Fragment spread may be unused
Graceful fallback:
soda-gql-lsp-cli binary is not found, skip this check silently — it is supplementary, not required.bun typecheck
What it checks:
On failure:
src/components/UserCard.tsx:25:10 - error TS2339: Property 'userName' does not exist on type 'UserFragment'
Fix suggestion:
Auto-fix offer: If the type error is due to stale codegen, offer: "Would you like me to re-run codegen to fix generated types?"
bun run soda-gql format --check
What it checks:
On failure:
Format check failed: 3 files need formatting
src/graphql/fragments.ts
src/graphql/operations.ts
src/graphql/queries.ts
Fix suggestion:
bun run soda-gql format
Auto-fix offer: Use AskUserQuestion: "Would you like me to auto-format the field selections?"
After all checks, provide a comprehensive summary:
All Checks Pass:
✅ soda-gql diagnostics: All checks passed!
Core checks (4/4):
✓ version-consistency
✓ duplicate-packages
✓ config-validation
✓ codegen-freshness
Extended checks (3/3):
✓ template-validation (typegen)
✓ type-check
✓ formatting
LSP diagnostics: ✓ available (no issues found)
[shown when hasLsp: true and soda-gql-lsp-cli is available]
Your soda-gql project is healthy!
Some Checks Failed:
⚠️ soda-gql diagnostics: Found issues
Core checks (2/4):
✓ version-consistency
✓ duplicate-packages
❌ config-validation: Missing required field 'outdir'
❌ codegen-freshness: Generated files are stale
Extended checks (2/3):
✓ template-validation
❌ type-check: 3 type errors found
✓ formatting
LSP diagnostics: ❌ 2 issues found (see per-file details above)
[shown when hasLsp: true and soda-gql-lsp-cli is available]
[shown as "⚠️ not available" when binary is missing or execution failed]
[omitted when hasLsp: false]
Recommended actions:
1. Fix config structure (see details above)
2. Run codegen to update generated files
3. Fix type errors in user code
If multiple fixable issues are found, offer a batch fix:
Use AskUserQuestion with multiSelect: true to ask: "Which issues would you like me to auto-fix?" Options:
For each selected fix, execute in order and report results:
Package version update:
bun add @soda-gql/core@latest @soda-gql/builder@latest [...]
Clean reinstall:
rm -rf node_modules
bun install
Run codegen:
bun run soda-gql codegen schema
Auto-format:
bun run soda-gql format
For config fixes and template/type errors, use Read/Write tools to make targeted fixes.
After auto-fixes, re-run the full diagnostic suite:
bun run soda-gql doctor
bun run soda-gql typegen
bun typecheck
bun run soda-gql format --check
Report final status to user.
Error: Command not found: soda-gql
Analysis:
Fix suggestion:
bun add -d @soda-gql/tools
bun run node_modules/.bin/soda-gql doctor
Error: Doctor command exited with code 1
Analysis:
Fix suggestion:
bun install to verify node_modules stateInform user about CI integration:
Tip: Add
soda-gql doctorto your CI pipeline:- name: Run soda-gql diagnostics run: | bun run soda-gql doctor bun run soda-gql typegen bun typecheck bun run soda-gql format --check
Suggest pre-commit hook setup:
Tip: Set up a pre-commit hook to auto-run diagnostics:
# .husky/pre-commit or similar bun run soda-gql doctor --quiet bun run soda-gql format git add -u
If working on schema changes, suggest watch workflow:
Tip: For active schema development:
- Terminal 1:
bun run soda-gql codegen schema --watch- Terminal 2:
bun typecheck --watchThis gives real-time feedback on schema changes.
Before completing this skill, ensure:
bun run soda-gql doctor executednpx claudepluginhub whatasoda/soda-gql-skills --plugin soda-gql-skillsIntegrates GraphQL Inspector into GitHub Actions, GitLab CI, and pipelines for automated schema diffing, operation validation, breaking change detection, and PR comments.
Validates OpenAPI, JSON Schema, and GraphQL API specs with linting, structural analysis, completeness checks, breaking change detection, and consistency enforcement. Generates reports.
Validates OpenAPI, Swagger, GraphQL schemas against backends like Express, FastAPI, Django. Detects breaking changes, generates TypeScript clients from .yaml, .json, .graphql specs.