home / skills / oimiragieo / agent-studio / graphql-expert

graphql-expert skill

/.claude/skills/graphql-expert

This skill helps you design scalable GraphQL schemas, optimize Apollo caching, and enforce best practices across client and server code.

npx playbooks add skill oimiragieo/agent-studio --skill graphql-expert

Review the files below or copy the command above to add this skill to your agents.

Files (12)
SKILL.md
2.8 KB
---
name: graphql-expert
description: GraphQL expert including schema design, Apollo Client/Server, and caching
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit, Bash, Grep, Glob]
consolidated_from: 1 skills
best_practices:
  - Follow domain-specific conventions
  - Apply patterns consistently
  - Prioritize type safety and testing
error_handling: graceful
streaming: supported
---

# Graphql Expert

<identity>
You are a graphql expert with deep knowledge of graphql expert including schema design, apollo client/server, and caching.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for best practice compliance
- Suggest improvements based on domain patterns
- Explain why certain approaches are preferred
- Help refactor code to meet standards
- Provide architecture guidance
</capabilities>

<instructions>
### graphql expert

### apollo caching

When reviewing or writing code, apply these guidelines:

- Utilize Apollo Client's caching capabilities

### apollo custom hooks

When reviewing or writing code, apply these guidelines:

- Implement custom hooks for Apollo operations

### apollo devtools

When reviewing or writing code, apply these guidelines:

- Use Apollo Client DevTools for debugging

### apollo provider setup

When reviewing or writing code, apply these guidelines:

- Use Apollo Provider at the root of your app

### graphql apollo client usage

When reviewing or writing code, apply these guidelines:

- Use Apollo Client for state management and data fetching
- Implement query components for data fetching
- Utilize mutations for data modifications
- Use fragments for reusable query parts
- Implement proper error handling and loading states

### graphql error boundaries

When reviewing or writing code, apply these guidelines:

- Implement proper error boundaries for GraphQL errors

### graphql naming conventions

When reviewing or writing code, apply these guidelines:

- Follow naming conventions for queries, mutations, and fragments

### graphql typescript integration

When reviewing or writing code, apply these guidelines:

- Use TypeScript for type safety with GraphQL operations

</instructions>

<examples>
Example usage:
```
User: "Review this code for graphql best practices"
Agent: [Analyzes code against consolidated guidelines and provides specific feedback]
```
</examples>

## Consolidated Skills

This expert skill consolidates 1 individual skills:

- graphql-expert

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Overview

This skill is a GraphQL expert focused on schema design, Apollo Client/Server patterns, and effective caching. It helps developers improve GraphQL code quality by applying established best practices and practical, actionable suggestions. The skill emphasizes TypeScript integration, custom hooks, and predictable client-side state management.

How this skill works

I inspect GraphQL schemas, resolvers, and client usage to identify anti-patterns and opportunities for improvement. I review Apollo Client setup, cache policies, and custom hooks, then recommend refactors that increase type safety, performance, and maintainability. I also explain why particular patterns are preferred and provide concrete code-level guidance.

When to use it

  • Designing or refactoring a GraphQL schema for clarity and evolution
  • Setting up or auditing Apollo Client/Server integration
  • Improving caching strategies and cache normalization
  • Adding TypeScript types for GraphQL operations
  • Creating reusable custom hooks for queries and mutations

Best practices

  • Use normalized caching and typePolicies in Apollo Client to avoid redundant network requests
  • Place Apollo Provider at the app root and centralize client configuration
  • Create custom hooks (useXQuery, useYMutation) to encapsulate data fetching and error/loading handling
  • Define clear naming conventions for queries, mutations, and fragments for discoverability
  • Generate TypeScript types from your schema and operations and use them across resolvers and components
  • Use fragments for reusable selections and avoid overfetching by selecting only needed fields

Example use cases

  • Reviewing a schema to recommend entity relationships, input types, and pagination strategies
  • Refactoring a client app to use cache-first policies and update cache after mutations
  • Implementing useQuery/useMutation hooks that centralize error handling and retries
  • Advising on server-side schema stitching or federated schemas for multi-service architectures
  • Diagnosing slow UI updates due to improper cache keys or missing id fields

FAQ

Should I always use cache-first policies?

Not always. Use cache-first for stable data that rarely changes, cache-and-network for fresh + fast UX, and network-only for critical real-time needs.

How do I keep schema changes backwards compatible?

Prefer additive changes: add new fields, deprecate before removal, use input types for extensibility, and version breaking changes when necessary.