GraphQL API Builder

Scaffolds production-shaped GraphQL APIs in TypeScript: typed schemas, resolvers wired to DataLoader, real-time subscriptions, and federated subgraphs. It's aimed at backend and fullstack engineers who already know GraphQL conceptually but don't want to hand-write boilerplate or rediscover the N+1 trap on every new field. The skill targets three concrete stacks — Apollo Server 4, Pothos (code-first schema-builder), and Nexus — and matches the conventions of whichever it detects in your repo.

When to use it

• Starting a new GraphQL service and choosing between SDL-first and code-first.
• Adding a resolver that fetches related entities (author → posts → comments) and you want batching from the start.
• Standing up graphql-ws subscriptions and the PubSub plumbing behind them.
• Splitting a monolithic schema into Apollo Federation subgraphs with @key and reference resolvers.
• Porting an Apollo SDL schema to Pothos builder calls, or vice versa.

How it works

For Pothos, it generates builder.objectRef, builder.queryType, and t.field definitions with the plugins you'd actually want — @pothos/plugin-dataloader, relay, and prisma — and respects your SchemaTypes generics. For Apollo Server 4, it produces typeDefs, resolvers, and a startStandaloneServer (or expressMiddleware) bootstrap. DataLoader is wired per-request in the context factory so caches don't leak between requests. Subscriptions use graphql-subscriptions PubSub (or a Redis-backed PubSub when you ask) plus a graphql-ws useServer setup on a separate WS path.

Example

curl -fsSL --create-dirs -o ~/.claude/skills/graphql-api-builder/SKILL.md https://claudeskil.com/skills/graphql-api-builder/SKILL.md

// Pothos: a batched, N+1-safe relation
const User = builder.loadableObject('User', {
  load: (ids: string[]) => db.user.findMany({ where: { id: { in: ids } } }),
  fields: (t) => ({
    id: t.exposeID('id'),
    posts: t.field({
      type: [Post],
      resolve: (user, _args, ctx) => ctx.loaders.postsByUser.load(user.id),
    }),
  }),
});

Tips & gotchas

• Build a fresh DataLoader per request. A loader created at module scope caches across users and serves stale or leaked data. The skill always instantiates loaders inside the context function.
• graphql-ws ≠ subscriptions-transport-ws. The latter is deprecated; generated clients and the server both use graphql-ws. Don't mix protocols.
• Federation needs the right build. Apollo Federation subgraphs use buildSubgraphSchema from @apollo/subgraph, not the plain makeExecutableSchema — reference resolvers (__resolveReference) are generated alongside each @key type.
• In Pothos, prefer loadableObject/loadableGroup over a manual loader map when the batching key is the object's own id.

FAQ

Code-first or SDL-first? Pothos/Nexus (code-first) give end-to-end type inference with no codegen step; Apollo SDL is more portable and tooling-friendly. The skill supports both and will follow your existing choice.

Does it handle the N+1 problem automatically? It generates DataLoader-backed resolvers for relations by default, but you still decide the batch key. It flags resolvers that fetch per-parent without a loader.

Can I add it to an existing Apollo server? Yes — it detects your resolvers and typeDefs structure and emits additions that match, rather than scaffolding a new server.