graphql-architect

Savant verdict: Unsafe

Savant's security policy blocks importing this skill.

Live evaluation

Not evaluated yet. Workspaces can request a live evaluation.

Security assessment

6 patterns found

• analysis-evasion: references/resolvers.md (partial)high · SKILL.md:38 · Referenced artifact was not completely inspected
• analysis-evasion: references/security.md (partial)high · SKILL.md:41 · Referenced artifact was not completely inspected
• analysis-evasion: references/migration-from-rest.md (partial)high · SKILL.md:42 · Referenced artifact was not completely inspected
• Tool Misuse: DELETE /users/:idhigh · references/migration-from-rest.md:50 · Tool parameters are crafted to achieve unintended or unsafe behavior. Parameter abuse can bypass intended safety checks (e.g. shell=True, --force, dangerous glob patterns).
• Tool Misuse: DELETE /api/users/:idhigh · references/migration-from-rest.md:290 · Tool parameters are crafted to achieve unintended or unsafe behavior. Parameter abuse can bypass intended safety checks (e.g. shell=True, --force, dangerous glob patterns).
• Excessive Agency: No limits on querymedium · references/migration-from-rest.md:1050 · Skill allows unbounded resource consumption (API calls, storage, compute). Without rate limits or quotas, a compromised or misbehaving agent can cause denial-of-service or cost overruns.

Structure

• The source hub's security checks flagged this skillGen Agent Trust Hub: fail (This skill provides a comprehensive architectural guide for GraphQL development, covering schema design, Apollo Federation, real-time subscriptions, and security best practices. All external references trace back to the author's own infrastructure and no malicious patterns were identified during the audit.); Runlayer: warn (2/7 files flagged)

SKILL.md

---
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
  version: "1.1.0"
  domain: api-architecture
  triggers: GraphQL, Apollo Federation, GraphQL schema, API graph, GraphQL subscriptions, Apollo Server, schema design, GraphQL resolvers, DataLoader
  role: architect
  scope: design
  output-format: schema
  related-skills: api-designer, microservices-architect, database-optimizer
---

# 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)

```graphql
# 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)

```js
// 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

```js
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](https://jeffallan.github.io/claude-skills/skills/api-architecture/graphql-architect/)