soda-gql-skills

soda-gql Claude Code Plugin

A Claude Code marketplace plugin that provides developer skills for working with soda-gql projects, including code generation, diagnostics, scaffolding, and API guidance.

Overview

This plugin enhances the Claude Code experience for soda-gql developers by providing specialized skills that understand your GraphQL schema and project configuration. The plugin works for both external users (via node_modules) and monorepo contributors (via workspace links) through a dual module resolution pattern.

Installation

For External Users

1. Install soda-gql in your project:

bun add @soda-gql/core
bun add -D @soda-gql/tools @soda-gql/config

2. Install the Claude Code plugin:

claude plugin marketplace add soda-gql-skills --source github:whatasoda/soda-gql-skills
claude plugin install soda-gql-skills@soda-gql-skills

Restart your Claude Code session to activate the skills.

For Monorepo Contributors

claude plugin marketplace add soda-gql-skills --source github:whatasoda/soda-gql-skills
claude plugin install soda-gql-skills@soda-gql-skills

All skills work out of the box via workspace package links after installation.

Prerequisites

• Bun installed: All scripts and commands use Bun as the runtime
• soda-gql project: You must have a soda-gql.config.{ts,js,mjs} file in your project root
• Dependencies installed: Run bun install to ensure all packages are available

Available Skills

/gql:codegen - Generate GraphQL System from Schema

Generates the GraphQL system files from your schema using the soda-gql codegen schema command.

What it does:

• Detects your project configuration
• Runs bun run soda-gql codegen schema to generate GraphQL system files
• Optionally runs bun run soda-gql typegen to generate prebuilt types
• Validates results with bun typecheck
• Reports errors and suggests fixes

When to use:

• Initial project setup after creating your schema file
• After modifying your GraphQL schema
• When you see type errors related to GraphQL types

Example:

/gql:codegen

/gql:scaffold - Generate GraphQL Fragments and Operations

Generates type-safe GraphQL fragments and operations from your schema with intelligent syntax selection.

What it does:

• Reads your GraphQL schema files
• Asks what you want to query
• Intelligently chooses between tagged template and callback builder syntax
• Generates code with proper imports and type safety
• Validates the generated code with bun run soda-gql typegen and bun typecheck
• Retries up to 3 times on errors

Syntax selection (automatic):

• Tagged template (fragment("Name", "Type")\...`, query("Name")`...``) for simple fragments and operations
• Options object (query("Name")({ variables, fields })()) when you need:
  • Fragment spreads in operations (...fragment.spread())
  • Field aliases
  • $colocate metadata
  • Fragment metadata callbacks

When to use:

• Creating new GraphQL queries or mutations
• Building reusable fragment definitions
• Need help understanding which syntax to use

Example:

/gql:scaffold get user profile with posts

/gql:doctor - Run Diagnostics and Health Checks

Runs comprehensive diagnostics on your soda-gql project and offers automated fixes.

What it does:

• Runs bun run soda-gql doctor for core checks:
  • version-consistency: Verifies all @soda-gql/* packages are on the same version
  • duplicate-packages: Detects duplicate package installations
  • config-validation: Validates your soda-gql.config.{ts,js,mjs} file
  • codegen-freshness: Checks if generated files are up-to-date with schema
• Runs extended checks:
  • bun run soda-gql typegen for template validation
  • bun typecheck for type errors
  • bun run soda-gql format --check for formatting issues
• Presents actionable fix suggestions for each issue
• Offers to auto-fix problems (codegen, formatting, etc.)

When to use:

• Debugging build or type errors
• Before committing changes
• After upgrading soda-gql packages
• When you suspect configuration issues

Example:

/gql:doctor

/gql:inspect - Inspect GraphQL Fragments and Operations

Analyzes GraphQL fragments and operations in your soda-gql project using the soda-gql-lsp-cli tool.

What it does:

• Lists all GraphQL symbols (fragments, operations) in a file with their types and line numbers
• Runs LSP diagnostics to detect field errors, type mismatches, and unused fragments
• Fetches schema type information for context
• Supports file path, symbol name, or interactive selection as input

When to use:

• Exploring what GraphQL definitions exist in a file
• Checking for errors in specific files
• Looking up schema type details
• Understanding fragment/operation structure

Example:

/gql:inspect src/graphql/fragments.ts
/gql:inspect UserFragment