Graphql Schema

Deep GraphQL schema workflow—modeling types, queries and mutations, N+1 and complexity limits, errors and pagination, federation risks, and evolution. Use wh...

Security Scan

This is an instruction-only GraphQL schema design workflow that contains guidance and checklists and does not request credentials, install software, or perform I/O — it is internally consistent with its stated purpose.

Purpose & Capability

The name and description match the SKILL.md content: detailed GraphQL schema design and review guidance. No unrelated capabilities, binaries, or credentials are requested.

Instruction Scope

The instructions are purely procedural and advisory (modeling, pagination, batching, authz, deprecation). They do not direct the agent to read files, access environment variables, call external endpoints, or transmit data.

Install Mechanism

No install spec or code files are present; this is instruction-only so nothing is written to disk or fetched at install time.

Credentials

The skill declares no environment variables, credentials, or config paths and the guidance does not reference any secrets — requested privileges are proportional (none).

Persistence & Privilege

always is false and the skill does not request persistent system presence or modification of other skills or system-wide settings.

Assessment

This skill is a safe, read-only set of GraphQL design guidelines. Consider: (1) it is advisory only — it won't run or validate your code; (2) ensure the recommendations match your stack (Apollo, Relay, federation patterns) before applying; (3) keep an eye on version/date — best practices evolve; and (4) if you need automated checks or enforcement, seek a code-based tool or CI integration rather than relying solely on this checklist.

GraphQL Schema (Deep Workflow)

GraphQL concentrates complexity on the server: resolver graphs, N+1 fetches, schema evolution, and field-level authorization.

When to Offer This Workflow

Trigger conditions:

• Designing a new GraphQL API or federated subgraph
• Latency or complexity incidents from client queries
• Need for safe schema deprecation and versioning

Initial offer:

Use six stages: (1) domain modeling, (2) operations surface, (3) performance patterns, (4) errors & partial results, (5) security & authz, (6) versioning & evolution). Confirm client patterns (Apollo, Relay) and gateway (if any).

---

Stage 1: Domain Modeling

Goal: Types reflect domain concepts; avoid dumping everything on Query; use input objects for mutations with validation.

---

Stage 2: Operations Surface

Goal: Queries for reads; mutations for writes; subscriptions only when justified (scaling and operational cost).

Pagination

• Prefer cursor-based connections for large lists (Relay-style edges/nodes)

---

Stage 3: Performance Patterns

Goal: DataLoader or batching for N+1; query complexity/depth/cost limits; optional persisted queries for public APIs.

---

Stage 4: Errors & Partial Results

Goal: Document semantics of errors alongside partial data; map domain failures to structured extensions.

---

Stage 5: Security & Authz

Goal: Enforce authorization at field/object level—not only at the top resolver.

---

Stage 6: Versioning & Evolution

Goal: Prefer additive changes; @deprecated with migration window; in federation, clear ownership of types and entities.

---

Final Review Checklist

• Schema reflects domain and operations
• Pagination and mutations idiomatic
• Batching and complexity limits in place
• Error behavior documented for clients
• Field-level authz enforced
• Deprecation policy defined

Tips for Effective Guidance

• N+1 is the default failure mode—plan batching early.
• Pair with rest-best-practices when REST and GraphQL coexist at the edge.

Handling Deviations

• Public APIs: consider persisted queries or allowlists to limit abusive queries.