SKILL.md
$2a
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:
- Schema definition (SDL with types and directives)
- Resolver implementation (with DataLoader patterns)
- Query/mutation/subscription examples
- 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