api-design-graphql
API Design GraphQL
Scope Boundaries
- Use when GraphQL schema boundaries, resolver contracts, and query safety must be defined.
- Use proactively when GraphQL SDL/resolver diffs appear in specs, manifests, or source.
- Use when clients need flexible field selection but query safety and authz boundaries are not yet explicit.
- Do not use for REST-first endpoint design; use
api-design-rest. - Do not use for storage internals; use
db-*.
Goal
Deliver GraphQL contracts that are safe to evolve and efficient at runtime.
Shared API Contract (Canonical)
- Use
../api-design-rest/references/api-governance-contract.mdas the canonical contract. - Optional consistency checks (only if your repository enforces manifest validation):
python3 ../api-design-rest/scripts/validate_api_contract.py --manifest <path/to/manifest.json>
- Use valid templates in
../api-design-rest/assets/. - Use transport decision reference:
../api-design-rest/references/transport-selection-matrix.md
- Use threshold derivation reference:
../api-design-rest/references/threshold-derivation-framework.md
- Do not redefine API artifact ID formats, states, or approval gates.
Implementation Templates
- GraphQL SDL template:
../api-design-rest/assets/graphql-schema-template.graphql
Inputs
- Required queries/mutations and consumer usage patterns
- Entity ownership and field-level authorization requirements
- Performance budgets for depth, complexity, and resolver latency
Outputs
- Schema contract (types, inputs, mutations, deprecation tags)
- Resolver behavior contract (authz, caching, batching, nullability semantics)
- Query safety controls (complexity/depth limits and abuse controls)
Workflow
- Define schema boundaries aligned with domain ownership, not backend table layout.
- Model inputs and payloads for forward-compatible evolution and explicit nullability.
- Set resolver authorization rules and avoid N+1 with batching strategy.
- Decide whether GraphQL is the primary transport or a gateway facade, and document alternatives.
- Define query complexity/depth limits and abuse safeguards for public access paths.
- Define error extension fields and trace correlation behavior.
- Derive threshold methods for query latency, complexity limits, and resolver concurrency.
- Validate compatibility, operational readiness, and canonical API contract compliance.
Quality Gates
- Schema evolution rules are explicit, including deprecations and migration notes.
- Resolver behavior is deterministic, authorized, and free of unbounded fan-out paths.
- Query safety limits are defined and enforced.
- Observability and error semantics are consistent with API governance contract.
Failure Handling
- Stop when schema changes break existing client contracts without approved version plan.
- Stop when resolver performance or query safety controls are undefined.
- Escalate when required security/governance approvers are missing.
More from kentoshimizu/sw-agent-skills
graph-algorithms
Graph algorithm workflow for modeling entities/relations and selecting traversal, path, ordering, or flow strategies. Use when correctness or performance depends on graph representation and algorithm choice; do not use for schema-only modeling or deployment topology planning.
14bash-style-guide
Style, review, and refactoring standards for Bash shell scripting. Trigger when `.sh` files, files with `#!/usr/bin/env bash` or `#!/bin/bash`, or CI workflow blocks with `shell: bash` are created, modified, or reviewed and Bash-specific quality controls (quoting safety, error handling, portability, readability) must be enforced. Do not use for generic POSIX `sh`, PowerShell, or language-specific application style rules. In multi-language pull requests, run together with other applicable `*-style-guide` skills.
11architecture-clean-architecture
Clean Architecture workflow for enforcing dependency direction, stable domain boundaries, and use-case-centered application design. Use when teams must separate business rules from frameworks and delivery mechanisms; do not use for isolated module cleanup without boundary implications.
11powershell-style-guide
Style, review, and refactoring standards for PowerShell scripting. Trigger when `.ps1`, `.psm1`, `.psd1` files, or CI workflow blocks with `shell: pwsh` or `shell: powershell` are created, modified, or reviewed and PowerShell-specific quality controls (error handling, parameter validation, readability, operational safety) must be enforced. Do not use for Bash, generic POSIX `sh`, or language-specific application style rules. In multi-language pull requests, run together with other applicable `*-style-guide` skills.
10github-codeowners-management
Govern CODEOWNERS rules so review routing reflects real ownership and risk boundaries on GitHub. Use when repository ownership mapping or mandatory reviewer rules must be defined, updated, or audited; do not use for non-GitHub runtime architecture or data-layer design.
9security-authentication
Security workflow for authentication architecture, credential lifecycle, and session/token assurance. Use when login, identity proofing, MFA, or session security decisions are required; do not use for authorization policy design or non-security quality tuning.
9