golang-graphql
Implements GraphQL APIs in Golang using gqlgen or graphql-go. Apply when building GraphQL servers, designing schemas, writing resolvers, handling subscriptions, or integrating GraphQL with existing Go HTTP services. Also apply when the codebase imports github.com/99designs/gqlgen or github.com/graph-gophers/graphql-go.
- Installs
- 37.1K
- Last 24h
- +152
- Trending rank
- #1469
- Security
- Pass
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/samber/cc-skills-golang --skill golang-graphql- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads golang-graphql automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
Persona: You are a Go GraphQL engineer. You design schemas deliberately, batch database access to prevent N+1, and treat query complexity limits as non-optional in production.
Modes:
- Build mode — generating new schemas, resolvers, or server setup: follow the skill's sequential instructions; launch a background agent to grep for existing resolver patterns and naming conventions before generating new code.
- Review mode — auditing a GraphQL codebase or PR: use a sub-agent to scan for N+1 resolver patterns, missing complexity caps, global DataLoaders, and introspection enabled in production, in parallel with reading the business logic.
Community default. A company skill that explicitly supersedes
samber/cc-skills-golang@golang-graphqlskill takes precedence.
Go GraphQL Best Practices
Both major libraries are schema-first: write SDL (.graphql files), bind Go resolvers. Choose based on project size and team preferences.
This skill is not exhaustive — refer to each library's official documentation and code examples for current API signatures:
- For Go package docs, symbols, versions, importers, and known vulnerabilities, → See
samber/cc-skills-golang@golang-pkg-go-devskill (godig), preferred over Context7 for Go package facts. - To navigate this library's usage in your own code (definitions, call sites, diagnostics), → See
samber/cc-skills-golang@golang-goplsskill (gopls). - Context7 remains a fallback for docs not indexed on pkg.go.dev.
Library Choice
| Library | Approach | Type safety | Build step | Best for |
|---|---|---|---|---|
github.com/99designs/gqlgen | Codegen | Compile-time | go generate | Large schemas, federation, strict types |
github.com/graph-gophers/graphql-go | Reflection | Parse-time | None | Simple schemas, fast iteration |
github.com/graphql-go/graphql | Code-first | Runtime | None | Avoid — verbose, no SDL |
Pick gqlgen when: Apollo Federation is required, schema is large (100+ types), or the team wants generated stubs and zero reflection overhead.
Pick graph-gophers when: schema is small/medium, the build pipeline should stay simple, or a dynamic schema is needed.
For deep-dive on each library, see gqlgen reference and graphql-go reference.
Schema Design
# ✓ Good — explicit nullability; ID scalar for opaque identifiers
type User {
id: ID!
email: String! # non-null: the server can always return this
bio: String # nullable: may be unset
posts(first: Int = 10, after: String): PostConnection!
}
# ✗ Bad — Int ID leaks implementation details, breaks client caching
type Post {
id: Int!
}
Nullability rule: mark a field ! only when the server can always return a value. A resolver error on a non-null field nulls the parent object, causing cascade failures; nullable fields only null the field itself.
Pagination: use Relay cursor connections (Connection/Edge/PageInfo) for list fields. Avoid offset pagination on large datasets — cursors are stable under concurrent writes.
Mutations: wrap results in an envelope type so clients receive business errors alongside partial results without polluting the GraphQL errors array:
type CreateUserPayload {
user: User
errors: [UserError!]!
}
Resolver Patterns
Keep resolvers thin — they translate GraphQL inputs to domain calls and domain responses to GraphQL outputs.
// ✓ Good — resolver delegates to service layer
func (r *mutationResolver) CreateUser(ctx context.Context, input model.CreateUserInput) (*model.CreateUserPayload, error) {
user, err := r.userService.Create(ctx, input.Email, input.Name)
if err != nil {
return nil, formatError(err)
}
return &model.CreateUserPayload{User: toGQLUser(user)}, nil
}
// ✗ Bad — SQL in resolver, no separation of concerns
func (r *queryResolver) User(ctx context.Context, id string) (*model.User, error) {
row := r.db.QueryRowContext(ctx, "SELECT * FROM users WHERE id = $1", id)
// ...
}
Use per-type resolver structs (userResolver, postResolver) rather than one monolithic resolver for all fields.
N+1 Prevention (DataLoaders)
Each User.posts resolver fires a SQL query per user without batching — O(n) DB calls for n users. DataLoaders solve this by coalescing per-field loads into a single batch query.
Critical rule: DataLoaders MUST be created per-request in HTTP middleware, never globally. A global DataLoader caches across requests — stale data, potential cross-user data leakage.
// ✓ Good — per-request DataLoader in middleware
func DataLoaderMiddleware(db *sql.DB, next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
loaders := &Loaders{
PostsByUserID: newPostsByUserIDLoader(r.Context(), db),
}
ctx := context.WithValue(r.Context(), loadersKey, loaders)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
// ✗ Bad — global DataLoader shared across all requests
var globalLoader = newPostsByUserIDLoader(context.Background(), db)
In gqlgen, mark batched fields with resolver: true in gqlgen.yml to force a dedicated resolver method. See gqlgen reference for full DataLoader wiring.
Authentication and Authorization
Two-layer model:
- HTTP middleware — extract and validate tokens, stash identity in
context.Context. - Schema directives (gqlgen) or resolver checks (graphql-go) — enforce per-field authorization.
// HTTP middleware layer (both libraries)
func AuthMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
token := r.Header.Get("Authorization")
user, err := validateToken(token)
if err != nil {
http.Error(w, "Unauthorized", http.StatusUnauthorized)
return
}
ctx := context.WithValue(r.Context(), userKey, user)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
In gqlgen, use @hasRole schema directives for field-level authorization — authorization policy lives in the schema, not scattered across resolvers. See gqlgen reference.
Error Handling
Never return raw internal errors — they leak SQL messages, stack traces, or service internals to clients.
// gqlgen — custom ErrorPresenter strips internal details
srv.SetErrorPresenter(func(ctx context.Context, err error) *gqlerror.Error {
var gqlErr *gqlerror.Error
if errors.As(err, &gqlErr) {
return gqlErr // already formatted
}
// log internal err here
return gqlerror.Errorf("internal error") // safe client message
})
// Add extension codes for client-side error handling
return nil, &gqlerror.Error{
Message: "user not found",
Extensions: map[string]any{"code": "NOT_FOUND"},
}
For graph-gophers, implement the ResolverError interface to attach Extensions(). See graphql-go reference.
Use graphql.AddError(ctx, err) in gqlgen for non-fatal field errors where the resolver can still return partial data.
For error wrapping patterns, see the samber/cc-skills-golang@golang-error-handling skill.
Subscriptions
Subscriptions use long-lived WebSocket connections. The critical discipline: always respect context cancellation — a leaked goroutine per disconnected client exhausts resources silently.
// ✓ Good — closes channel when client disconnects
func (r *subscriptionResolver) MessageAdded(ctx context.Context, room string) (<-chan *model.Message, error) {
ch := make(chan *model.Message, 1)
sub := r.pubsub.Subscribe(room) // subscribe once before the goroutine
go func() {
defer close(ch) // always close; signals iteration to stop
for {
select {
case <-ctx.Done():
return // client disconnected
case msg := <-sub:
select {
case ch <- msg:
case <-ctx.Done():
return
}
}
}
}()
return ch, nil
}
// ✗ Bad — goroutine leaks forever when client disconnects
func (r *subscriptionResolver) MessageAdded(ctx context.Context, room string) (<-chan *model.Message, error) {
ch := make(chan *model.Message, 1)
go func() {
for msg := range r.pubsub.Subscribe(room) {
ch <- msg // blocks forever after client gone
}
}()
return ch, nil
}
Performance and Safety
Production GraphQL servers require explicit limits. Without them, a single deeply nested query exhausts CPU and memory.
// gqlgen — wire these into every production handler
srv := handler.NewDefaultServer(es)
srv.Use(extension.FixedComplexityLimit(200)) // max cost per query
// Gate introspection — only in non-production environments
if os.Getenv("ENV") != "production" {
srv.Use(extension.Introspection{})
}
For graph-gophers: graphql.MaxDepth(10) and graphql.MaxParallelism(10) options at ParseSchema time.
Query allow-listing: in production, consider persisted queries (gqlgen APQ extension) to reject arbitrary query strings.
Common Mistakes
| Mistake | Why it matters | Fix |
|---|---|---|
| N+1 queries in child resolvers | One SQL per parent row → O(n) DB calls | Use per-request DataLoader |
| Global DataLoader | Cross-request cache — stale data, data leaks | Create DataLoader in request middleware |
Editing models_gen.go directly | Next go generate wipes hand edits | Use autobind or models.<T>.model in gqlgen.yml |
Forgetting go generate after schema change | Resolver interface mismatch at compile time | Re-run go tool gqlgen generate |
int field in graph-gophers resolver | Library requires int32 for Int scalar | Use int32 (or float64 for Float) |
| Introspection enabled in production | Exposes full schema to attackers | Gate with ENV check |
| No complexity cap | Deeply nested query → CPU/memory DoS | extension.FixedComplexityLimit(N) |
| Leaking DB errors from resolvers | Exposes SQL internals to clients | Wrap in ErrorPresenter / ResolverError |
| Subscription goroutine leak | Client disconnect → goroutine runs forever | defer close(ch) + select ctx.Done() |
| Nullable field for always-required data | Clients must null-check everywhere | Mark ! in schema; return error from resolver |
Deep Dives
- gqlgen reference — codegen workflow,
gqlgen.yml, DataLoaders, Federation v2, directives - graphql-go reference — reflection resolver model, type mapping, tracing
- Testing — gqlgen client harness, gqltesting, httptest patterns
Cross-References
- → See
samber/cc-skills-golang@golang-contextskill for context propagation in resolvers and subscriptions - → See
samber/cc-skills-golang@golang-error-handlingskill for error wrapping and sentinel patterns - → See
samber/cc-skills-golang@golang-testingskill for table-driven and integration test patterns - → See
samber/cc-skills-golang@golang-observabilityskill for tracing and metrics in resolvers - → See
samber/cc-skills-golang@golang-securityskill for input validation and injection prevention - → See
samber/cc-skills-golang@golang-databaseskill for N+1 query patterns and DataLoader database batching
References
If you encounter a bug or unexpected behavior in gqlgen, open an issue at https://github.com/99designs/gqlgen/issues.
If you encounter a bug or unexpected behavior in graph-gophers/graphql-go, open an issue at https://github.com/graph-gophers/graphql-go/issues.
FAQ
What does the golang-graphql skill do?
Implements GraphQL APIs in Golang using gqlgen or graphql-go. Apply when building GraphQL servers, designing schemas, writing resolvers, handling subscriptions, or integrating GraphQL with existing Go HTTP services. Also apply when the codebase imports github.com/99designs/gqlgen or github.com/graph-gophers/graphql-go.
How do I install golang-graphql?
Run npx skills add https://github.com/samber/cc-skills-golang --skill golang-graphql in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/golang-graphql/ (personal) or .claude/skills/golang-graphql/ (project).
Which AI agents can use golang-graphql?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is golang-graphql safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains golang-graphql?
It is published by samber in samber/cc-skills-golang. It has 37,135 recorded installs.
More from samber/cc-skills-golang
golang-code-style
samber/cc-skills-golang
Golang code style conventions — line length and breaking, variable declarations, control flow clarity, when comments help vs hurt. Use when writing or reviewing Go code, asking about style or clarity, or establishing project coding standards. Not for naming conventions (→ See samber/cc-skills-golang@golang-naming skill), linter configuration (→ See samber/cc-skills-golang@golang-lint skill), or doc comments (→ See samber/cc-skills-golang@golang-documentation skill).
golang-testing
samber/cc-skills-golang
Production-ready Golang tests — table-driven tests, testify suites and mocks, parallel tests, fuzzing, fixtures, goroutine leak detection with goleak, snapshot testing, code coverage, integration tests, idiomatic test naming. Use when writing or reviewing Go tests, choosing a testing approach, setting up Go test CI, or debugging flaky/slow tests. For testify-specific APIs see samber/cc-skills-golang@golang-stretchr-testify; for measurement methodology see samber/cc-skills-golang@golang-benchmark.
golang-error-handling
samber/cc-skills-golang
Idiomatic Golang error handling — creation, wrapping with %w, errors.Is/As, errors.Join, custom error types, sentinel errors, panic/recover, the single handling rule, structured logging with slog, HTTP request logging middleware, and samber/oops for production errors. Built to make logs usable at scale with log aggregation 3rd-party tools. Apply when creating, wrapping, inspecting, or logging errors in Go code. For samber/oops specifics → See samber/cc-skills-golang@golang-samber-oops skill; for slog handler ecosystem → See samber/cc-skills-golang@golang-samber-slog skill.
golang-security
samber/cc-skills-golang
Security best practices and vulnerability prevention for Golang — injection (SQL, command, XSS), cryptography, path traversal, SSRF and HTTP security headers, cookies, secrets management, memory safety, PII in logs, STRIDE/DREAD threat modeling, plus gosec SAST, race detection, and fuzz testing. Apply when writing, reviewing, or auditing Go code for security, or when touching crypto, file or network I/O, secrets, user input, or authentication. Not for non-exploitable defensive bugs such as nil panics or slice aliasing (→ See samber/cc-skills-golang@golang-safety skill), dependency vulnerability scanning with govulncheck (→ See samber/cc-skills-golang@golang-dependency-management skill), or wiring security scanners into CI pipelines (→ See samber/cc-skills-golang@golang-continuous-integration skill).
golang-design-patterns
samber/cc-skills-golang
Idiomatic Golang design patterns — functional options, constructor APIs, init() and global-state avoidance, enums, panic vs error decisions, resource management and lifecycle, graceful shutdown, timeouts and retries, streaming and iterators, and architecture styles (clean, hexagonal, DDD, flat). Apply when choosing between architectural patterns, implementing functional options, designing constructor APIs, setting up graceful shutdown, applying resilience patterns, or asking which idiomatic Go pattern fits a specific problem. Not for wiring a DI container or comparing DI libraries (→ See samber/cc-skills-golang@golang-dependency-injection skill), nor for error wrapping, errors.Is/As, or logging mechanics (→ See samber/cc-skills-golang@golang-error-handling skill).
golang-performance
samber/cc-skills-golang
Golang performance optimization patterns and methodology - if X bottleneck, then apply Y. Covers allocation reduction, CPU efficiency, memory layout, GC tuning, pooling, caching, and hot-path optimization. Use when profiling or benchmarks have identified a bottleneck and you need the right optimization pattern to fix it. Also use when performing performance code review to suggest improvements or benchmarks that could help identify quick performance gains. Not for measurement methodology (→ See samber/cc-skills-golang@golang-benchmark skill) or debugging workflow (→ See samber/cc-skills-golang@golang-troubleshooting skill).
Popular backend & apis skills
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.
design-an-interface
mattpocock/skills
Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".