Claude Code for GraphQL Directives (2026)
Claude Code for GraphQL Directives Workflow
GraphQL directives provide a powerful way to annotate and transform your schema, but managing them across a growing codebase can quickly become overwhelming. A well-designed Claude Code skill can automate directive creation, enforce naming conventions, validate usage patterns, and even generate documentation. This guide walks you through building a comprehensive workflow for working with GraphQL directives using Claude Code skills.
Understanding GraphQL Directives
Before diving into the workflow, let’s establish what directives can do for your GraphQL API. Directives are annotations that start with @ and can modify query execution or type definitions. They’re incredibly useful for conditional field inclusion, deprecated markers, formatting, authorization, and more.
type User {
id: ID!
email: String! @auth(requires: ADMIN)
name: String
createdAt: DateTime! @date(format: "yyyy-MM-dd")
role: Role! @deprecated(reason: "Use permissions field instead")
}
The most common built-in directives are @skip, @include, and @deprecated, but custom directives use the true power of this feature. They let you express cross-cutting concerns, caching policies, rate limiting, formatting rules, access control, directly in the schema, where every client and every developer can see them at a glance.
Directive Location Types
GraphQL directives can be applied at two levels: schema definition directives (SDL) that annotate your type definitions, and executable directives that appear in client queries. Understanding the distinction shapes how you design your skill.
| Type | Example Locations | Common Use Cases |
|---|---|---|
| SDL directives | OBJECT, FIELD_DEFINITION, ENUM |
Auth, caching, deprecation, formatting |
| Executable directives | FIELD, FRAGMENT_SPREAD, INLINE_FRAGMENT |
Conditional inclusion, feature flags |
| Both | ARGUMENT_DEFINITION |
Input validation, transformation |
SDL directives are the more common target for automation because they live in your schema files, benefit from linting, and need consistent conventions across a team. Executable directives are usually simpler and client-driven.
Building Your GraphQL Directives Skill
Skill Structure and Front Matter
Start by creating a skill file that defines its capabilities clearly. The front matter should declare the skill’s purpose and available tools:
---
name: graphql-directives
description: Workflow for creating, validating, and managing GraphQL directives
tools:
- Read
- Write
- Bash
- Glob
---
Declaring tools explicitly in the skill front matter helps Claude Code pre-approve the right permission scopes for the session. A directive skill needs file read access for scanning existing schema files, write access for generating new directive definitions, and Bash access for running validation scripts or schema checks.
Directive Generation Patterns
One of the most valuable automations is generating boilerplate for common directive types. Here’s how to structure directive generation in your skill:
Authentication Directive Generator:
directive @auth(requires: AuthLevel!) on FIELD_DEFINITION | OBJECT
enum AuthLevel {
PUBLIC
USER
ADMIN
SUPERADMIN
}
Your skill should generate both the directive definition and any corresponding resolver middleware. A practical workflow involves:
- Analyzing the target schema for fields requiring authorization
- Determining the appropriate auth level for each field based on naming conventions and existing patterns
- Generating the directive definition in the appropriate schema file
- Creating middleware or resolver logic that enforces the directive at runtime
Caching Directive Generator:
directive @cache(
maxAge: Int!
scope: CacheScope = PUBLIC
staleWhileRevalidate: Int
) on FIELD_DEFINITION | OBJECT
enum CacheScope {
PUBLIC
PRIVATE
}
Rate Limiting Directive:
directive @rateLimit(
max: Int!
window: String!
message: String
) on FIELD_DEFINITION
For each of these patterns, your skill should be able to produce not just the SDL definition but also the accompanying resolver implementation. A Claude Code skill that generates the directive definition without the resolver leaves developers with half the work done, the definition is inert until the resolver actually enforces it.
Resolver Implementation Alongside Directives
A directive without enforcement logic is documentation, not functionality. Your skill workflow should pair each directive with its resolver stub:
// Generated by graphql-directives skill
const { SchemaDirectiveVisitor } = require('graphql-tools');
const { defaultFieldResolver } = require('graphql');
class AuthDirective extends SchemaDirectiveVisitor {
visitFieldDefinition(field) {
const { resolve = defaultFieldResolver } = field;
const { requires } = this.args;
field.resolve = async function (source, args, context, info) {
if (!context.user) {
throw new Error('Authentication required');
}
const userLevel = AUTH_LEVELS[context.user.role];
const requiredLevel = AUTH_LEVELS[requires];
if (userLevel < requiredLevel) {
throw new Error(`Requires ${requires} access`);
}
return resolve.call(this, source, args, context, info);
};
}
}
const AUTH_LEVELS = {
PUBLIC: 0,
USER: 1,
ADMIN: 2,
SUPERADMIN: 3,
};
module.exports = { AuthDirective };
This pattern, directive definition plus resolver implementation in a single generation step, is what separates a useful directive skill from a template generator.
Validation and Convention Enforcement
A solid skill should validate directives against your team’s conventions. Create rules that check:
- Naming conventions: Directives should use consistent casing. If your team uses camelCase for multi-word directives (
@rateLimit), a validator should flag any new directive using underscores (@rate_limit). - Placement validation: Certain directives should only appear on specific schema locations. An
@authdirective on anINPUT_OBJECTprobably indicates a misunderstanding of the data flow. - Argument validation: Required arguments are present and properly typed. A
@cachedirective without amaxAgeargument has no useful default behavior. - Circular dependencies: Directives that invoke other directives don’t create unresolvable chains.
- Conflict detection: Two directives applied to the same field that contradict each other (one says
@cache(scope: PUBLIC)and another says@auth(requires: ADMIN)) need a resolution policy.
Example validation logic in your skill
BUILTIN_DIRECTIVES = {'skip', 'include', 'deprecated', 'specifiedBy'}
def validate_directive(directive):
errors = []
warnings = []
if not directive.name.startswith('@'):
errors.append(f"Directive name must start with @: {directive.name}")
clean_name = directive.name.lstrip('@')
if clean_name in BUILTIN_DIRECTIVES:
errors.append(f"Cannot redefine built-in directive: {directive.name}")
if '_' in clean_name:
warnings.append(f"Consider camelCase for directive name: {directive.name}")
if not directive.locations:
errors.append(f"Directive must declare at least one valid location: {directive.name}")
for arg in directive.arguments:
if arg.required and arg.default_value is not None:
warnings.append(f"Required argument {arg.name} has a default value, consider making it optional")
return errors, warnings
Surfacing warnings separately from errors lets developers make informed decisions rather than enforcing one rigid style. An error blocks generation; a warning prompts a conversation.
Practical Workflow Examples
Schema Evolution Workflow
When your API evolves, directives need to migrate accordingly. Use Claude Code to handle this systematically:
- Scan existing directives across your schema files to build an inventory
- Identify deprecation patterns that should be applied to fields scheduled for removal
- Generate migration scripts that add new directives while preserving old ones during transition periods
- Update client queries that reference deprecated fields by suggesting or generating the replacement patterns
Find all custom directives in your schema
grep -r "^directive" --include="*.graphql" schema/
Find all fields using a specific directive
grep -r "@auth" --include="*.graphql" schema/
A Claude Code skill can wrap these searches and present the results in a structured format, then offer to apply changes across all matching files in a single operation, something that would require careful manual work otherwise.
Schema Audit Report
Before a major API version, run a directive audit to understand what you’re working with:
Input: existing schema with mixed directive usage
type Query {
publicData: [DataItem!]!
userData: [DataItem!]! @auth(requires: USER)
adminReport: AdminReport! @auth(requires: ADMIN) @cache(maxAge: 300)
legacyEndpoint: LegacyData @deprecated(reason: "Use newEndpoint instead")
}
A skill that scans this and produces:
- Total custom directives in use: 3 (
@auth,@cache,@deprecated) - Fields with no access control: 1 (
publicData. intentional or oversight?) - Fields with conflicting concerns: 1 (
adminReport. cached but auth-gated, verify cache key includes user context) - Deprecated fields still receiving traffic (requires integration with analytics): check separately
That kind of audit catches bugs and design issues that code review routinely misses.
Multi-Environment Directive Management
Different environments may require different directive configurations. Your skill can manage this by:
- Maintaining environment-specific directive configurations in separate schema overlay files
- Generating the appropriate schema variants for each environment at build time
- Validating that required directives exist in all environments before deployment
schema.base.graphql. shared across all environments
type Product {
id: ID!
name: String!
price: Float!
}
schema.production.graphql. extends base with prod-specific directives
extend type Product {
price: Float! @cache(maxAge: 60, scope: PUBLIC)
}
schema.development.graphql. extends base with dev-specific directives
extend type Product {
price: Float! @mock(value: "29.99")
}
A directive skill that understands this layered approach can generate environment-specific schemas on demand, validate that the layers don’t introduce contradictions, and document which directives are active in which environments.
Documentation Generation
Transform directive definitions into usable documentation automatically. A directive definition is already structured data, the skill should exploit that:
@auth Directive
Location: `FIELD_DEFINITION | OBJECT`
Arguments:
- `requires: AuthLevel!` - Required permission level. Throws if the authenticated user's role is below this level.
Valid values for `requires`: `PUBLIC`, `USER`, `ADMIN`, `SUPERADMIN`
```graphql
type SecureData {
sensitiveField: String @auth(requires: ADMIN)
publicField: String @auth(requires: PUBLIC)
}
Resolver behavior: Checks context.user.role against the AUTH_LEVELS map. Throws AuthenticationError if no user present; throws ForbiddenError if user level is insufficient.
Owner: Platform team Since: v2.1.0
This level of auto-generated documentation is accurate by definition, it's derived directly from the schema and the resolver implementation, and it stays in sync automatically when the skill regenerates it.
## Actionable Best Practices
1. Keep Directives Focused
Each directive should have a single responsibility. Instead of one complex `@fieldConfig` directive handling caching, validation, and transformation, create separate directives that compose cleanly. Composition is easier to reason about, test, and document independently.
2. Document Directive Intent in the Schema
Every custom directive should have a description string in the SDL itself, not just in a separate doc file. This description shows up in introspection queries and any tooling that reads your schema:
```graphql
"""
Restricts field access to users with sufficient authorization level.
Throws AuthenticationError if no user is present in context.
Throws ForbiddenError if user level is insufficient.
"""
directive @auth(requires: AuthLevel!) on FIELD_DEFINITION | OBJECT
Your skill can enforce this rule as a validation: directives without description strings generate a warning during the audit workflow.
- Version Your Directives Explicitly
When evolving directives, maintain backward compatibility or version them explicitly. Use naming like @authV2 during transitions, and maintain a migration guide in the directive’s description. A skill that generates versioned directives can also generate the migration instructions automatically.
- Test Directive Behavior Systematically
Include test generation in your workflow. For each directive, your skill should produce:
- Unit tests for resolver middleware covering the happy path and each error condition
- Integration tests for directive application on real schema fields
- Schema validation tests that confirm the directive can only appear in declared locations
// Generated unit test for AuthDirective
describe('AuthDirective', () => {
it('allows access when user meets the required level', async () => {
const context = { user: { role: 'ADMIN' } };
const result = await resolveWithDirective({ requires: 'USER' }, context);
expect(result).toBeDefined();
});
it('throws when user level is insufficient', async () => {
const context = { user: { role: 'USER' } };
await expect(
resolveWithDirective({ requires: 'ADMIN' }, context)
).rejects.toThrow('Requires ADMIN access');
});
it('throws when no user is present in context', async () => {
const context = {};
await expect(
resolveWithDirective({ requires: 'USER' }, context)
).rejects.toThrow('Authentication required');
});
});
- Maintain a Directive Registry
Keep a central registry of all directives with their purposes, versions, and owners. This makes it easy to find existing solutions before creating new directives, a problem that compounds significantly in large organizations where multiple teams add directives independently.
A registry entry should capture at minimum: directive name, purpose, locations, arguments, owner team, version introduced, and whether it’s currently active or deprecated.
Integrating with Your Development Workflow
Your GraphQL directives skill should integrate smoothly with other development tools. Consider these integration points:
IDE extensions: Generate VS Code or JetBrains snippets for common directives so developers can insert them with a keystroke. A snippet for @auth that auto-completes with the requires argument and the AuthLevel enum options removes a class of typo-driven bugs.
Pre-commit hooks: Validate directive usage before code lands in version control. A schema file with an undefined directive or a directive applied to an unsupported location should fail the commit with a clear error message, not a confusing runtime error discovered in staging.
CI/CD pipelines: Include directive validation in your build process. The schema should be validated as part of every build, and directive-specific rules (no deprecated directive usage in new fields, all @auth directives have corresponding resolver implementations) can run as a separate job with actionable output.
API documentation: Auto-generate directive reference docs as part of your documentation build. When the schema changes, the docs rebuild. The directive documentation is never out of date because it can’t be, it’s derived from the schema itself.
Conclusion
A well-crafted Claude Code skill for GraphQL directives transforms what is a tedious manual process into an efficient, consistent workflow. By automating generation, validation, documentation, and migration, you ensure your schema remains maintainable as it grows. Start with the basics, directive generation and validation, then expand into documentation and cross-file analysis as your needs evolve.
The key is to build incrementally, adding capabilities as you identify problems in your current workflow. Your directive skill should grow alongside your GraphQL API, providing increasing value as your schema matures. Teams that invest in this kind of tooling early find that their schemas stay coherent through growth phases that would otherwise produce an inconsistent tangle of ad-hoc annotations.
The payoff compounds: a schema with well-managed directives is easier to audit, easier to document, easier to migrate, and easier to hand off to new developers who can read the intent of every field directly from its annotations.
Related Reading
- Claude Code for GraphQL Code Generation Workflow
- Claude Code for GraphQL Codegen Workflow Tutorial
- Claude Code for GraphQL Complexity Workflow Guide
Built by theluckystrike. More at zovo.one
Find the right skill → Browse 155+ skills in our Skill Finder.
See Also
Try it: Paste your error into our Error Diagnostic for an instant fix.