About

Imported from shipshitdev/skills (skills/graphql-architect/SKILL.md). Install upstream with npx skills add shipshitdev/skills --skill graphql-architect. Copyright stays with the author.

GraphQL Architect

Name: graphql-architect
Author: shipshitdev

Design GraphQL APIs that are explicit, stable, and performant.

Use This Skill For

New GraphQL schemas or modules
Resolver and mutation design
Pagination, filtering, and search
N+1 reduction and batching
Authorization, validation, and error-shaping for GraphQL

Workflow

1. Read the Existing GraphQL Shape

Inspect schema files, resolver structure, and context setup
Find at least 3 existing resolver or schema patterns before adding new ones
Match the dominant conventions for naming, nullability, and error handling

2. Design the Contract Before Implementation

Start from client use cases, not database tables
Define the schema shape first: queries, mutations, input types, output types
Keep types stable and explicit; avoid ambiguous fields or overloaded mutations

3. Implement Resolver Boundaries Cleanly

Keep resolvers thin; push business logic into services
Validate inputs at the API boundary
Enforce authorization close to the entry point
Avoid leaking database details directly into schema types

4. Control Performance Early

Use batching/data loaders where related fields fan out
Prefer cursor pagination over ad hoc offset pagination for large lists
Avoid fields that trigger hidden expensive work without clear client intent
Measure N+1 risk any time a list returns nested entities

5. Verify Client Ergonomics

Field names should describe domain concepts, not storage details
Nullability must reflect real guarantees
Mutation results should return enough data for immediate UI updates
Errors should be consistent and actionable

Core Rules

Queries read; mutations change state
Input types and output types should be distinct
Keep mutation names verb-first and specific
Prefer explicit enums over magic strings
Add deprecation before removal when evolving schemas

Common Pitfalls

Catch-all mutations like updateThing
Returning giant nested objects by default
Resolver logic that talks directly to the database and the network in one layer
Hiding authorization failures behind nulls without a deliberate contract
Adding fields without thinking through cache keys or client churn

Output

When using this skill, produce:

Proposed schema/resolver changes
Notes on performance and authorization implications
Any migration or client-impact risks

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/shipshitdev-skills-graphql-architect/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

shipshitdev-skills-graphql-architect.ocm.jsonjson

{
  "ocm": "1",
  "id": "shipshitdev-skills-graphql-architect",
  "kind": "skill",
  "name": "graphql-architect",
  "description": "Design and review GraphQL schemas, resolvers, mutations, pagination, and data-loading patterns. Use when building or refactoring GraphQL APIs, adding fields, fixing resolver design, or improving GraphQL performance and safety.",
  "publisher": "shipshitdev",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "graphql",
      "api-design",
      "schema",
      "resolvers",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Design and review GraphQL schemas, resolvers, mutations, pagination, and data-loading patterns. Use when building or refactoring GraphQL APIs, adding fields, fixing resolver design, or improving GraphQL performance and safety."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/shipshitdev/skills",
      "path": "skills/graphql-architect/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/shipshitdev/skills/blob/HEAD/skills/graphql-architect/SKILL.md",
      "key": "shipshitdev/skills/skills/graphql-architect/SKILL.md"
    }
  },
  "instructions": "# GraphQL Architect\n\nDesign GraphQL APIs that are explicit, stable, and performant.\n\n## Use This Skill For\n\n- New GraphQL schemas or modules\n- Resolver and mutation design\n- Pagination, filtering, and search\n- N+1 reduction and batching\n- Authorization, validation, and error-shaping for GraphQL\n\n## Workflow\n\n### 1. Read the Existing GraphQL Shape\n\n- Inspect schema files, resolver structure, and context setup\n- Find at least 3 existing resolver or schema patterns before adding new ones\n- Match the dominant conventions for naming, nullability, and error handling\n\n### 2. Design the Contract Befor",
  "cost": {
    "context_tokens": 598
  }
}

Fetch it by URL: GET /api/v1/registry/shipshitdev-skills-graphql-architect/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.