Skip to content

JPeetz/agent-skills / skills/api-backend/graphql-api-development

graphql-api-development

Verified

Use this skill when designing, implementing, or optimizing a GraphQL API: schema-first design, resolver architecture with DataLoader to prevent N+1 queries, mutation patterns with idempotency, real-time subscriptions, Apollo Federation for distributed graphs, security hardening (depth limiting, rate limiting, authorization), and production performance (persisted queries, caching, CDN integration). Activates on requests to design a GraphQL schema, review resolvers for N+1 queries, set up federation, add subscriptions, fix pagination, or harden a GraphQL API.

FileKindSize
CHANGELOG.mdmarkdown2.5 KB
LICENSEother1.0 KB
SKILL.mdskill md33.5 KB
evals/evals.jsonconfig3.7 KB
evals/test_cases.jsonconfig11.5 KB
references/graphql-patterns.mdmarkdown34.9 KB
scripts/validate_skill.pyscript29.9 KB

CHANGELOG.md

View on GitHub
# Changelog — GraphQL API Development Agent Skill

All notable changes to this skill package will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## v1.0.0 — 2026-06-23

### Added
- Initial release by Skill Foundry
- Comprehensive schema design workflow: naming conventions, pagination
  patterns (Relay cursor + simplified offset), typed union error handling,
  schema documentation standards
- Resolver architecture patterns: parent-to-child delegation, field-level
  authorization, DataLoader setup for N+1 prevention with critical rules
- Mutation design patterns: single input types, idempotency key support,
  payload types, thin-resolver/thick-service architecture
- Real-time subscription patterns: event-driven PubSub, filtered
  subscriptions with `withFilter`, WebSocket authentication, async iterator
  teardown and cleanup
- Apollo Federation principles: entity definition with `@key`, reference
  resolvers, `@shareable`/`@requires`/`@tag` usage, contract-based API
  versioning, `_entities` query testing
- Security hardening: depth limiting (graphql-depth-limit), query cost
  analysis, per-operation rate limiting, schema-directive-based authz,
  introspection gating
- Performance optimization: Automatic Persisted Queries (APQ), field-level
  `@cacheControl` directives, CDN GET-based caching, response compression,
  `@defer`/`@stream` incremental delivery, Apollo inline tracing
- Quick Reference table: 8 dimensions with key indicators
- Common Pitfalls & Anti-Patterns: 10 GraphQL-specific anti-patterns with
  descriptions and correct approaches
- 10-item GraphQL Quality Checklist
- Safety Rules: 8 absolute rules for production GraphQL APIs
- Platform Compatibility Notes for all 8 agentic platforms
- 7 eval cases (5 positive, 2 near-miss negatives) with expected behaviors
- PEP 723 validation script for schema and resolver output validation
- Comprehensive `references/graphql-patterns.md` reference document
- SEO-optimized description with primary keyword clusters for AI engine
  discovery
## v1.0.1 — 2026-06-25

### Changed
- Published to GitHub repository (JPeetz/agent-skills)
- Part of Skill Foundry Run 004

## v1.1.0 — 2026-10-28

### Changed
- Description rewritten to trigger form ("Use this skill when..."); removed keyword-cluster dump from frontmatter
- Added evals/evals.json with 7 cases (5 positive, 2 near-miss negatives) grounded in SKILL.md triggers and quality checklist
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall