GraphQL Architect

What it does

When your agent uses it

• Designing a GraphQL schema from a business domain
• Splitting a graph into federated subgraphs with entities and keys
• Fixing N+1 queries in resolvers with DataLoader
• Adding depth and complexity limits to a public GraphQL API
• Migrating a REST API to GraphQL

Example prompts

• “Design a GraphQL schema for a bookstore with authors, books and reviews, plus example queries.”
• “Split our users and orders types into two federated subgraphs with a shared User entity.”
• “The orders resolver runs one query per item, so batch it with DataLoader.”
• “Add query depth limiting and a complexity threshold to our Apollo server.”

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

1. 1Domain Modeling - Map business domains to GraphQL type system
2. 2Design Schema - Create types, interfaces, unions with federation directives
3. 3Validate Schema - Run schema composition check; confirm all @key entities resolve correctly
4. 4Implement Resolvers - Write efficient resolvers with DataLoader patterns
5. 5Secure - Add query complexity limits, depth limiting, field-level auth; validate complexity thresholds before deployment
6. 6Optimize - Performance tune with caching, persisted queries, monitoring

What it can do on your machine

Read from SKILL.md and the folder at commit 1be15d8. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are javascript and graphql).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • github.com
  • synergetic.solutions
  • jeffallan.github.io

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

GraphQL Architect loads about 1.3k tokens when it runs, and up to ~20k if it reads all its reference files. Until then it costs about 55 tokens; SKILL.md has 351 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~55

When it runs · the whole SKILL.md, loaded when a task matches

~1.3k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~20k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Jeffallan/claude-skills at commit 1be15d8, republished under its MIT licence (© Jeffallan). 351 words, ~1,317 tokens.

name

graphql-architect

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.

license

MIT

metadata.author

https://github.com/Jeffallan

metadata.company

https://synergetic.solutions

metadata.version

1.1.0

metadata.domain

api-architecture

metadata.triggers

GraphQL, Apollo Federation, GraphQL schema, API graph, GraphQL subscriptions, Apollo Server, schema design, GraphQL resolvers, DataLoader

metadata.role

architect

metadata.scope

design

metadata.output-format

schema

metadata.related-skills

api-designer, microservices-architect, database-optimizer

# 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!
}

// 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),
  },
};

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

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

© Jeffallan, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 6 other files (references) in skills/graphql-architect of Jeffallan/claude-skills.

• SKILL.md
• references/federation.md
• references/migration-from-rest.md
• references/resolvers.md
• references/schema-design.md
• references/security.md
• references/subscriptions.md

Open the folder on GitHubat commit 1be15d8