Generate Comprehensive GraphQL Schema Documentation

This skill documents GraphQL APIs comprehensively and in a developer-friendly way, treating the schema definition as the source of truth. Documentation is written schema-first - using GraphQL's own directives and description strings as the primary source, kept in sync as the schema evolves, and leveraging introspection for auto-generated sections - and developer-experience-focused, with a working example for every operation, documented error scenarios and edge cases, and real request/response pairs rather than theoretical schema descriptions alone. Type and field descriptions use triple-quoted docstrings covering format constraints, uniqueness rules, and status-dependent access implications directly on the schema; mutation docstrings state what's required, what's returned, and which named error codes can occur, with input-type field constraints spelled out inline.

Use it when documenting a GraphQL API for external or cross-team consumption, not an internal-only schema with no outside consumers. It is not meant to drift from the schema: descriptions belong on the schema itself via docstrings and the @deprecated directive so documentation and API stay in sync automatically rather than living in a separate wiki that goes stale.

Given a GraphQL schema, it produces an overview section (API purpose and use cases, authentication requirements, rate limiting, base URL and endpoint details), interactive query examples paired with separate variables and response JSON blocks - including cursor-based pagination with inline comments explaining how to pass the cursor and end-cursor for the next page - a standardized error response format (an errors array with a message, an extensions object carrying a code, field, and timestamp, and a path, alongside null data) with five named common error codes (AUTHENTICATION_REQUIRED, FORBIDDEN, VALIDATION_ERROR, NOT_FOUND, RATE_LIMITED), and subscription documentation covering real-time updates via a union-typed event payload that requires authentication and read permission on the underlying resource.

"""
Represents a user in the system with authentication and profile information.
Users can be in different states: active, suspended, or pending verification.
"""
type User {
  """Unique identifier for the user (UUID format)"""
  id: ID!
  
  """
  User's email address. Must be unique across the system.
  Used for authentication and notifications.
  """
  email: String!
  
  """
  User's display name. Can be updated by the user.
  Must be between 2-50 characters.
  """
  displayName: String!
  
  """ISO 8601 timestamp when the user account was created"""
  createdAt: DateTime!
  
  """
  User's current status. Affects what operations they can perform.
  - ACTIVE: Full access to all features
  - SUSPENDED: Read-only access, cannot perform mutations
  - PENDING: Awaiting email verification
  """
  status: UserStatus!
}

Pagination is documented in the cursor-based Connection pattern (recommended over offset-based), with each field's role spelled out inline - the cursor for pagination position and endCursor passed as the after argument for the next page. Documentation maintenance covers schema evolution (deprecation reasons and migration paths via @deprecated, a changelog of breaking changes, version-specific examples), testing (schema validation examples, resolver unit tests, integration tests, performance testing approaches), and developer onboarding (progressive learning paths, sandbox environments, common workflow examples, troubleshooting guides for frequent issues).

API teams documenting a GraphQL schema for external or cross-team developers who need working examples, not just type signatures - covering authentication, pagination, error handling, subscriptions, and a maintenance process that keeps docs synced to schema changes as the API evolves.