guynhsichngeodiecguynhsichngeodiec/cc-skills-golang/skills/golang-grpc/SKILL.md

golang-grpc

Skill0 starsChanged 7 months agoMITView on GitHub

Provides gRPC usage guidelines, protobuf organization, and production-ready patterns for Golang microservices. Use when implementing, reviewing, or debugging gRPC servers/clients, writing proto files, setting up interceptors, handling gRPC errors with status codes, configuring TLS/mTLS, testing with bufconn, or working with streaming RPCs.

We split this skill into the rules it gives an agent

7 rules. 2 are common, 0 are distinctive, and 5 are very specific to this project.

2
Common
Most of the 8 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Treat gRPC as a pure transport layer — keep it separate from business logic.
line 33
Common:
Use interceptors for cross-cutting concerns (logging, auth, recovery) — keeps business logic clean
line 60
Very specific:
Use GracefulStop() with a timeout fallback to Stop() — drains in-flight RPCs while preventing hangs
line 61
Very specific:
Use round_robin with headless Kubernetes services via dns:/// scheme
line 98
Very specific:
Always return gRPC errors using status.Error with a specific code — a raw error becomes codes.Unknown, telling the client nothing …
line 124
Common:
Prefer streaming over large single messages — avoids per-message size limits and lowers memory pressure.
line 160
Very specific:
Use bufconn for in-memory connections that exercise the full gRPC stack (serialization, interceptors, metadata) without network overhead.
line 175

“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Persona: You are a Go distributed systems engineer. You design gRPC services for correctness and operability — proper status codes, deadlines, interceptors, and graceful shutdown matter as much as the happy path.

Modes:

Build mode — implementing a new gRPC server or client from scratch.
Review mode — auditing existing gRPC code for correctness, security, and operability issues.

Go gRPC Best Practices

Treat gRPC as a pure transport layer — keep it separate from business logic. The official Go implementation is google.golang.org/grpc.

This skill is not exhaustive. Please refer to library documentation and code examples for more information. Context7 can help as a discoverability platform.

Quick Reference

Concern	Package / Tool
Service definition	`protoc` or `buf` with `.proto` files
Code generation	`protoc-gen-go`, `protoc-gen-go-grpc`
Error handling	`google.golang.org/grpc/status` with `codes`
Rich error details	`google.golang.org/genproto/googleapis/rpc/errdetails`
Interceptors	`grpc.ChainUnaryInterceptor`, `grpc.ChainStreamInterceptor`
Middleware ecosystem	`github.com/grpc-ecosystem/go-grpc-middleware`
Testing	`google.golang.org/grpc/test/bufconn`
TLS / mTLS	`google.golang.org/grpc/credentials`
Health checks	`google.golang.org/grpc/health`

Proto File Organization

Organize by domain with versioned directories (proto/user/v1/). Always use Request/Response wrapper messages — bare types like string cannot have fields added later. Generate with buf generate or protoc.

Proto & code generation reference

Server Implementation

Implement health check service (grpc_health_v1) — Kubernetes probes need it to determine readiness
Use interceptors for cross-cutting concerns (logging, auth, recovery) — keeps business logic clean
Use GracefulStop() with a timeout fallback to Stop() — drains in-flight RPCs while preventing hangs
Disable reflection in production — it exposes your full API surface

srv := grpc.NewServer(
    grpc.ChainUnaryInterceptor(loggingInterceptor, recoveryInterceptor),
)
pb.RegisterUserServiceServer(srv, svc)
healthpb.RegisterHealthServer(srv, health.NewServer())

go srv.Serve(lis)

// On shutdown signal:
stopped := make(chan struct{})
go func() { srv.GracefulStop(); close(stopped) }()
select {
case <-stopped:
case <-time.After(15 * time.Second):
    srv.Stop()
}

Interceptor Pattern

func loggingInterceptor(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
    start := time.Now()
    resp, err := handler(ctx, req)
    log.Printf("method=%s duration=%s code=%s", info.FullMethod, time.Since(start), status.Code(err))
    return resp, err
}

Client Implementation

Reuse connections — gRPC multiplexes RPCs on a single HTTP/2 connection; one-per-request wastes TCP/TLS handshakes
Set deadlines on every call (context.WithTimeout) — without one, a slow upstream hangs goroutines indefinitely
Use round_robin with headless Kubernetes services via dns:/// scheme
Pass metadata (auth tokens, trace IDs) via metadata.NewOutgoingContext

conn, err := grpc.NewClient("dns:///user-service:50051",
    grpc.WithTransportCredentials(creds),
    grpc.WithDefaultServiceConfig(`{
        "loadBalancingPolicy": "round_robin",
        "methodConfig": [{
            "name": [{"service": ""}],
            "timeout": "5s",
            "retryPolicy": {
                "maxAttempts": 3,
                "initialBackoff": "0.1s",
                "maxBackoff": "1s",
                "backoffMultiplier": 2,
                "retryableStatusCodes": ["UNAVAILABLE"]
            }
        }]
    }`),
)
client := pb.NewUserServiceClient(conn)

Error Handling

Always return gRPC errors using status.Error with a specific code — a raw error becomes codes.Unknown, telling the client nothing actionable. Clients use codes to decide retry vs fail-fast vs degrade.

Code	When to Use
`InvalidArgument`	Malformed input (missing field, bad format)
`NotFound`	Entity does not exist
`AlreadyExists`	Create failed, entity exists
`PermissionDenied`	Caller lacks permission
`Unauthenticated`	Missing or invalid token
`FailedPrecondition`	System not in required state
`ResourceExhausted`	Rate limit or quota exceeded
`Unavailable`	Transient issue, safe to retry
`Internal`	Unexpected bug
`DeadlineExceeded`	Timeout

// ✗ Bad — caller gets codes.Unknown, can't decide whether to retry
return nil, fmt.Errorf("user not found")

// ✓ Good — specific code lets clients act appropriately
if errors.Is(err, ErrNotFound) {
    return nil, status.Errorf(codes.NotFound, "user %q not found", req.UserId)
}
return nil, status.Errorf(codes.Internal, "lookup failed: %v", err)

For field-level validation errors, attach errdetails.BadRequest via status.WithDetails.

Streaming

Pattern	Use Case
Server streaming	Server sends a sequence (log tailing, result sets)
Client streaming	Client sends a sequence, server responds once (file upload, batch)
Bidirectional	Both send independently (chat, real-time sync)

Prefer streaming over large single messages — avoids per-message size limits and lowers memory pressure.

func (s *server) ListUsers(req *pb.ListUsersRequest, stream pb.UserService_ListUsersServer) error {
    for _, u := range users {
        if err := stream.Send(u); err != nil {
            return err
        }
    }
    return nil
}

Testing

Use bufconn for in-memory connections that exercise the full gRPC stack (serialization, interceptors, metadata) without network overhead. Always test that error scenarios return the expected gRPC status codes.

Testing patterns and examples

Security

TLS MUST be enabled in production — credentials travel in metadata
For service-to-service auth, use mTLS or delegate to a service mesh (Istio, Linkerd)
For user auth, implement credentials.PerRPCCredentials and validate tokens in an auth interceptor
Reflection SHOULD be disabled in production to prevent API discovery

Performance

Setting	Purpose	Typical Value
`keepalive.ServerParameters.Time`	Ping interval for idle connections	30s
`keepalive.ServerParameters.Timeout`	Ping ack timeout	10s
`grpc.MaxRecvMsgSize`	Override 4 MB default for large payloads	16 MB
Connection pooling	Multiple conns for high-load streaming	4 connections

Most services do not need connection pooling — profile before adding complexity.

Common Mistakes

Mistake	Fix
Returning raw `error`	Becomes `codes.Unknown` — client can't decide whether to retry. Use `status.Errorf` with a specific code
No deadline on client calls	Slow upstream hangs indefinitely. Always `context.WithTimeout`
New connection per request	Wastes TCP/TLS handshakes. Create once, reuse — HTTP/2 multiplexes RPCs
Reflection enabled in production	Lets attackers enumerate every method. Enable only in dev/staging
`codes.Internal` for all errors	Wrong codes break client retry logic. `Unavailable` triggers retry; `InvalidArgument` does not
Bare types as RPC arguments	Can't add fields to `string`. Wrapper messages allow backwards-compatible evolution
Missing health check service	Kubernetes can't determine readiness, kills pods during deployments
Ignoring context cancellation	Long operations continue after caller gave up. Check `ctx.Err()`

Cross-References

→ See samber/cc-skills-golang@golang-context skill for deadline and cancellation patterns
→ See samber/cc-skills-golang@golang-error-handling skill for gRPC error to Go error mapping
→ See samber/cc-skills-golang@golang-observability skill for gRPC interceptors (logging, tracing, metrics)
→ See samber/cc-skills-golang@golang-testing skill for gRPC testing with bufconn

Download now (ZIP)

Other versions11 projects use a version of this.
Word for word · 3
alexastrum/skl★ 11100% same
poizoncoded/skills★ 2100% same
gccli/skills★ 0100% same
Edited · 7
samber/cc-skills-golang★ 3.6k89% same
klawisha012/agentsync★ 1890% same
tstapler/dotfiles★ 889% same
rockcookies/skills★ 188% same
VerifiedOrganic/onboard★ 196% same
imMamdouhaboammar/tiktok-growth-automation-mesh★ 089% same
rzisso/golang-skills★ 089% same
Wrote their own version · 1
reagin/agent-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Used alongsideProjects with it also use golang-google-wire, golang-graphql and 9 more.
Other files people use alongside this one.
- alexastrumSkill
  golang-google-wire
  Compile-time dependency injection in Golang using google/wire — wire.NewSet, wire.Build, wire.Bind (interface→concrete), wire.Struct, wire.Value, wire.InterfaceValue, wire.FieldsOf, cleanup functions, //go:build wireinject injector files, and generated wire_gen.go. Apply when using or adopting google/wire, when the codebase imports `github.com/google/wire`, or when wiring an application graph at compile time via `wire.Build`. For runtime DI with reflection, see `samber/cc-skills-golang@golang-uber-dig` skill.
  Also in 6 projects that use this
- alexastrumSkill
  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`.
  Also in 6 projects that use this
- rockcookiesSkill
  golang-pkg-go-dev
  Golang package and module documentation and exploration via `godig`, a pkg.go.dev API client (CLI + MCP server) — package docs, API references, symbols, code examples, available versions, importers (who imports a package), licenses, and known vulnerabilities. Read-only, no auth. Use for looking up any Go/Golang library's documentation, API signatures, usage examples, which versions exist, whether a dependency has CVEs, or who imports a package — prefer this over Context7 for any Go package or module. Triggers on: how to use a Go library, Go API docs, import usage, code examples, pkg.go.dev. Not for upgrading dependencies (→ See `golang-dependency-management` skill) or choosing a library (→ See `golang-popular-libraries` skill). Not for local symbols, or for navigating an already-used dependency's resolved source, call sites, or generic instantiations — → See `golang-gopls` skill for those.
  Also in 4 projects that use this
- jkeddariSkill
  golang-gopls
  Golang semantic code intelligence with the official gopls language server: definitions, references, symbols, call and implementation hierarchies, diagnostics, formatting, code actions, safe rename, extract, inline, and package API discovery. Use when navigating or refactoring a local Go workspace or when semantic analysis is safer than text search.
  Also in 4 projects that use this
- jkeddariSkill
  golang-refactoring
  Golang refactoring workflow for safe structural change: blast-radius discovery, coverage-adaptive safety nets, semantic rename and extract operations, package moves, import-cycle removal, staged commits, and behavior-preserving verification. Use when restructuring existing Go code without intentionally changing its public behavior.
  Also in 4 projects that use this
- +6 more from alexastrum
In this repository35 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- golang-benchmarkSkill
- golang-cliSkill
- golang-code-styleSkill
- golang-concurrencySkill
- golang-contextSkill
- golang-continuous-integrationSkill
- golang-databaseSkill
- golang-data-structuresSkill
- golang-dependency-injectionSkill
- golang-dependency-managementSkill
- golang-design-patternsSkill
- golang-documentationSkill
- golang-error-handlingSkill
- golang-lintSkill
- golang-modernizeSkill
- golang-namingSkill
- golang-observabilitySkill
- golang-performanceSkill
- golang-popular-librariesSkill
- golang-project-layoutSkill
- golang-safetySkill
- golang-samber-doSkill
- golang-samber-hotSkill
- golang-samber-loSkill
- golang-samber-moSkill
- golang-samber-oopsSkill
- golang-samber-roSkill
- golang-samber-slogSkill
- golang-securitySkill
- golang-stay-updatedSkill
- golang-stretchr-testifySkill
- golang-structs-interfacesSkill
- golang-testingSkill
- golang-troubleshootingSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free