Graphql Architect
Design and scaffold Apollo Federation subgraphs, entity keys, and resolver patterns when you are splitting a GraphQL API across services.
Overview
Graphql-architect is an agent skill most often used in Build (also Ship → Review) that designs Apollo Federation subgraphs, entity keys, and reference resolvers for multi-service GraphQL APIs.
Install
npx skills add https://github.com/jeffallan/claude-skills --skill graphql-architectWhat is this skill?
- Apollo Federation v2.5 subgraph setup with buildSubgraphSchema and TypeScript Apollo Server examples
- Entity @key definitions, __resolveReference, and cross-subgraph reference patterns
- @shareable and @interfaceObject directive usage in multi-subgraph schemas
- Concrete users and products subgraph snippets you can adapt into a monorepo or polyrepo layout
- Examples target Apollo Federation specification v2.5 via @link import lists in subgraph schemas
Adoption & trust: 2.3k installs on skills.sh; 9.7k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are splitting one GraphQL API into federated subgraphs but are unsure how to define keys, references, and server wiring without breaking the supergraph.
Who is it for?
Solo builders shipping a SaaS or internal API who already chose GraphQL and need a federation-shaped backend layout with working starter code.
Skip if: Greenfield apps that only need a single small schema, or teams that want REST-only backends with no GraphQL gateway.
When should I use this skill?
You are designing or implementing a multi-subgraph GraphQL API with Apollo Federation entity keys and reference resolvers.
What do I get? / Deliverables
You get subgraph-ready schemas and Apollo Server resolver patterns that align with Federation v2.5 entity and reference rules for your services.
- Subgraph schema.graphql files with federation directives
- Apollo Server subgraph bootstrap and resolver modules
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Federated GraphQL architecture is decided and implemented while building the API surface, which is the canonical first touchpoint in the solo-builder journey. The skill centers on schema design, subgraph servers, and backend resolver wiring—not frontend components or DevOps pipelines.
Where it fits
Stand up a users subgraph with @key(fields: "id") and __resolveReference before adding a products subgraph.
Model cross-service fields so the gateway can resolve Product references from the users subgraph without duplicating catalog data.
Audit new @shareable fields and interface objects before publishing a schema change to production.
How it compares
Use this for federated GraphQL architecture patterns, not a one-file CRUD tutorial or a frontend component library skill.
Common Questions / FAQ
Who is graphql-architect for?
Indie developers and small teams building multi-service GraphQL backends with Apollo Federation who want the agent to produce subgraph schemas and resolver stubs, not vague architecture slides.
When should I use graphql-architect?
Use it in Build → Backend while defining subgraph boundaries and @key fields, and again in Ship → Review when you add new types and need to check reference resolvers and directive usage.
Is graphql-architect safe to install?
It is documentation and code-pattern guidance; check the Security Audits panel on this page and still review exposed fields, auth, and data leakage in your own public GraphQL schemas.
SKILL.md
READMESKILL.md - Graphql Architect
# Apollo Federation ## Subgraph Setup ```typescript // users-subgraph/schema.graphql extend schema @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@shareable"]) type User @key(fields: "id") { id: ID! email: String! username: String! createdAt: DateTime! } type Query { user(id: ID!): User users: [User!]! } // users-subgraph/resolvers.ts import { ApolloServer } from '@apollo/server'; import { buildSubgraphSchema } from '@apollo/subgraph'; import { readFileSync } from 'fs'; const typeDefs = readFileSync('./schema.graphql', 'utf8'); const resolvers = { User: { __resolveReference: async ( reference: { id: string }, context: Context ): Promise<User> => { return context.dataSources.users.findById(reference.id); }, }, Query: { user: async (parent, args: { id: string }, context: Context) => { return context.dataSources.users.findById(args.id); }, users: async (parent, args, context: Context) => { return context.dataSources.users.findAll(); }, }, }; const server = new ApolloServer({ schema: buildSubgraphSchema([{ typeDefs, resolvers }]), }); ``` ## Entity Keys and References ```graphql # products-subgraph/schema.graphql extend schema @link(url: "https://specs.apollo.dev/federation/v2.5", import: [ "@key", "@shareable", "@interfaceObject" ]) # Single key field type Product @key(fields: "id") { id: ID! name: String! price: Float! sku: String! @shareable } # Composite key type Variant @key(fields: "productId sku") { productId: ID! sku: String! size: String! color: String! } # Multiple keys (different ways to identify) type Review @key(fields: "id") @key(fields: "productId authorId") { id: ID! productId: ID! authorId: ID! rating: Int! content: String! } ``` ## Extending Types Across Subgraphs ```graphql # users-subgraph: owns User type User @key(fields: "id") { id: ID! email: String! username: String! } # posts-subgraph: extends User with posts extend type User @key(fields: "id") { id: ID! @external posts: [Post!]! } type Post @key(fields: "id") { id: ID! title: String! content: String! authorId: ID! author: User! } ``` ```typescript // posts-subgraph/resolvers.ts const resolvers = { User: { // Reference resolver: fetch User stub by id __resolveReference: async ( reference: { id: string }, context: Context ) => { return { id: reference.id }; }, // Field resolver: resolve posts for User posts: async (user: { id: string }, args, context: Context) => { return context.dataSources.posts.findByAuthor(user.id); }, }, Post: { // Resolve author as User entity reference author: (post: Post) => { return { __typename: 'User', id: post.authorId }; }, }, }; ``` ## Federation Directives ```graphql extend schema @link(url: "https://specs.apollo.dev/federation/v2.5", import: [ "@key", "@requires", "@provides", "@external", "@shareable", "@override", "@inaccessible", "@tag" ]) # @key: Define entity with primary key type Product @key(fields: "id") { id: ID! name: String! } # @external: Field defined in another subgraph extend type User @key(fields: "id") { id: ID! @external email: String! @external isVerified: Boolean! @external } # @requires: Field needs external data extend type User @key(fields: "id") { id: ID! @external email: String! @external isVerified: Boolean! @external # Can only compute if we have email and isVerified canPost: Boolean! @requires(fields: "email isVerified") } # @provides: Optimization hint type Post @key(fields: "id") { id: ID! author: User! @provides(fields: "username") } # @shareable: Field can be resolved by multiple subgraphs type Product @key(fields: "id") { id: ID! sku: String! @shareable name: String! } # @override: Migration between subgraphs type Product @key(fields: "id") { id: ID! #