JPeetz/agent-skills / skills/api-backend/graphql-api-development
graphql-api-development
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 2.5 KB |
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 33.5 KB |
| evals/evals.json | config | 3.7 KB |
| evals/test_cases.json | config | 11.5 KB |
| references/graphql-patterns.md | markdown | 34.9 KB |
| scripts/validate_skill.py | script | 29.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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |