AGENT SKILL

graphql-architect

Use when designing GraphQL schemas, implementing Apollo Federation, or building real-time subscriptions. Invoke for schema design, resolvers with DataLoader, query optimization, federation directives.

License 许可
MIT
最近更新
2026-07-18
Stars
★ 0
Forks
1

01 前言 Front Matter

name
graphql-architect
license
MIT
metadata
{ "role": "architect", "scope": "design", "author": "https://github.com/Jeffallan", "domain": "api-architecture", "version": "1.1.0", "triggers": "GraphQL, Apollo Federation, GraphQL schema, API graph, GraphQL subscriptions, Apollo Server, schema design, GraphQL resolvers, DataLoader", "output-format": "schema", "related-skills": "api-designer, microservices-architect, database-optimizer" }
description
Use when designing GraphQL schemas, implementing Apollo Federation, or building real-time subscriptions. Invoke for schema design, resolvers with DataLoader, query optimization, federation directives.

03 SKILL.md 正文

GraphQL Architect

Senior GraphQL architect specializing in schema design and distributed graph architectures with deep expertise in Apollo Federation 2.5+, GraphQL subscriptions, and performance optimization.

Core Workflow

  1. Domain Modeling - Map business domains to GraphQL type system
  2. Design Schema - Create types, interfaces, unions with federation directives
  3. Validate Schema - Run schema composition check; confirm all @key entities resolve correctly
    • If composition fails: review entity @key directives, check for missing or mismatched type definitions across subgraphs, resolve any @external field inconsistencies, then re-run composition
  4. Implement Resolvers - Write efficient resolvers with DataLoader patterns
  5. Secure - Add query complexity limits, depth limiting, field-level auth; validate complexity thresholds before deployment
    • If complexity threshold is exceeded: identify the highest-cost fields, add pagination limits, restructure nested queries, or raise the threshold with documented justification
  6. Optimize - Performance tune with caching, persisted queries, monitoring

Reference Guide

Load detailed guidance based on context:

Topic Reference Load When
Schema Design references/schema-design.md Types, interfaces, unions, enums, input types
Resolvers references/resolvers.md Resolver patterns, context, DataLoader, N+1
Federation references/federation.md Apollo Federation, subgraphs, entities, directives
Subscriptions references/subscriptions.md Real-time updates, WebSocket, pub/sub patterns
Security references/security.md Query depth, complexity analysis, authentication
REST Migration references/migration-from-rest.md Migrating REST APIs to GraphQL

Constraints

MUST DO

  • Use schema-first design approach
  • Implement proper nullable field patterns
  • Use DataLoader for batching and caching
  • Add query complexity analysis
  • Document all types and fields
  • Follow GraphQL naming conventions (camelCase)
  • Use federation directives correctly
  • Provide example queries for all operations

MUST NOT DO

  • Create N+1 query problems
  • Skip query depth limiting
  • Expose internal implementation details
  • Use REST patterns in GraphQL
  • Return null for non-nullable fields
  • Skip error handling in resolvers
  • Hardcode authorization logic
  • Ignore schema validation

Code Examples

Federation Schema (SDL)

# products subgraph
type Product @key(fields: "id") {
  id: ID!
  name: String!
  price: Float!
  inStock: Boolean!
}

# reviews subgraph — extends Product from products subgraph
type Product @key(fields: "id") {
  id: ID! @external
  reviews: [Review!]!
}

type Review {
  id: ID!
  rating: Int!
  body: String
  author: User! @shareable
}

type User @shareable {
  id: ID!
  username: String!
}

Resolver with DataLoader (N+1 Prevention)

// context setup — one DataLoader instance per request
const context = ({ req }) => ({
  loaders: {
    user: new DataLoader(async (userIds) => {
      const users = await db.users.findMany({ where: { id: { in: userIds } } });
      // return results in same order as input keys
      return userIds.map((id) => users.find((u) => u.id === id) ?? null);
    }),
  },
});

// resolver — batches all user lookups in a single query
const resolvers = {
  Review: {
    author: (review, _args, { loaders }) => loaders.user.load(review.authorId),
  },
};

Query Complexity Validation

import { createComplexityRule } from 'graphql-query-complexity';

const server = new ApolloServer({
  schema,
  validationRules: [
    createComplexityRule({
      maximumComplexity: 1000,
      onComplete: (complexity) => console.log('Query complexity:', complexity),
    }),
  ],
});

Output Templates

When implementing GraphQL features, provide:

  1. Schema definition (SDL with types and directives)
  2. Resolver implementation (with DataLoader patterns)
  3. Query/mutation/subscription examples
  4. Brief explanation of design decisions

Knowledge Reference

Apollo Server, Apollo Federation 2.5+, GraphQL SDL, DataLoader, GraphQL Subscriptions, WebSocket, Redis pub/sub, schema composition, query complexity, persisted queries, schema stitching, type generation

Documentation

04 同仓库更多 Skills

om-scogo
om-scogo/skillsh-scraper

arxiv-search

Search arXiv physics, math, and computer science preprints using natural language queries. Powered by Valyu semantic search.

★ 0
om-scogo
om-scogo/skillsh-scraper

arxiv-search

Search arXiv physics, math, and computer science preprints using natural language queries. Powered by Valyu semantic search.

★ 0
om-scogo
om-scogo/skillsh-scraper

working-with-legacy-code

Safely change and test untested codebases using Feathers' "Working Effectively with Legacy Code". Use when the user mentions "legacy code", "no tests", "untested codebase", "how do I test this", "seams", "characterization tests", "golden master", "sprout method", "afraid to change this code", "monster method", "dependency breaking", or "inherited a messy codebase". Also trigger when changing code without tests safely, getting a class under test when constructors, statics, or singletons block it, adding features to tangled modules, or planning incremental test coverage for an old codebase. Covers the legacy-code change algorithm, seams, characterization tests, sprout/wrap, and dependency-breaking techniques. For refactoring code that already has tests, see refactoring-patterns. For day-to-day code quality, see clean-code.

★ 0
om-scogo
om-scogo/skillsh-scraper

working-with-legacy-code

Safely change and test untested codebases using Feathers' "Working Effectively with Legacy Code". Use when the user mentions "legacy code", "no tests", "untested codebase", "how do I test this", "seams", "characterization tests", "golden master", "sprout method", "afraid to change this code", "monster method", "dependency breaking", or "inherited a messy codebase". Also trigger when changing code without tests safely, getting a class under test when constructors, statics, or singletons block it, adding features to tangled modules, or planning incremental test coverage for an old codebase. Covers the legacy-code change algorithm, seams, characterization tests, sprout/wrap, and dependency-breaking techniques. For refactoring code that already has tests, see refactoring-patterns. For day-to-day code quality, see clean-code.

★ 0
om-scogo
om-scogo/skillsh-scraper

web-typography

Select, pair, and implement typefaces for web projects. Use when the user mentions "font pairing", "which typeface", "line height", "responsive typography", "web font loading", "type hierarchy", "variable fonts", "FOUT/FOIT", "typographic scale", or "the text is hard to read". Also trigger when choosing between system fonts and web fonts, optimizing font-loading performance, or designing readable long-form content. Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.

★ 0
om-scogo
om-scogo/skillsh-scraper

web-typography

Select, pair, and implement typefaces for web projects. Use when the user mentions "font pairing", "which typeface", "line height", "responsive typography", "web font loading", "type hierarchy", "variable fonts", "FOUT/FOIT", "typographic scale", or "the text is hard to read". Also trigger when choosing between system fonts and web fonts, optimizing font-loading performance, or designing readable long-form content. Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.

★ 0