{"id":"80368a99-cc6e-40cb-94ae-170c7214ad35","shortId":"QJBqws","kind":"skill","title":"grpc-golang","tagline":"Build production-ready gRPC services in Go with mTLS, streaming, and observability. Use when designing Protobuf contracts with Buf or implementing secure service-to-service transport.","description":"# gRPC Golang (gRPC-Go)\n\n## Overview\n\nComprehensive guide for designing and implementing production-grade gRPC services in Go. Covers contract standardization with Buf, transport layer security via mTLS, and deep observability with OpenTelemetry interceptors.\n\n## Use this skill when\n\n- Designing microservices communication with gRPC in Go.\n- Building high-performance internal APIs using Protobuf.\n- Implementing streaming workloads (unidirectional or bidirectional).\n- Standardizing API contracts using Protobuf and Buf.\n- Configuring mTLS for service-to-service authentication.\n\n## Do not use this skill when\n\n- Building pure REST/HTTP public APIs without gRPC requirements.\n- Modifying legacy `.proto` files without the ability to introduce a new API version (e.g., `api.v2`) or ensure backward compatibility.\n- Managing service mesh traffic routing (e.g., Istio/Linkerd), which is outside the application code scope.\n\n## Step-by-Step Guide\n\n1. **Confirm Technical Context**: Identify Go version, gRPC-Go version, and whether the project uses Buf or raw protoc.\n2. **Confirm Requirements**: Identify mTLS needs, load patterns (unary/streaming), SLOs, and message size limits.\n3. **Plan Schema**: Define package versioning (e.g., `api.v1`), resource types, and error mapping.\n4. **Security Design**: Implement mTLS for service-to-service authentication.\n5. **Observability**: Configure interceptors for tracing, metrics, and structured logging.\n6. **Verification**: Always run `buf lint` and breaking change checks before finalizing code generation.\n\nRefer to `resources/implementation-playbook.md` for detailed patterns, code examples, and anti-patterns.\n\n## Examples\n\n### Example 1: Defining a Service & Message (v1 API)\n\n```proto\nsyntax = \"proto3\";\npackage api.v1;\noption go_package = \"github.com/org/repo/gen/api/v1;apiv1\";\n\nservice UserService {\n  rpc GetUser(GetUserRequest) returns (GetUserResponse);\n}\n\nmessage User {\n  string id = 1;\n  string name = 2;\n}\n\nmessage GetUserRequest {\n  string id = 1;\n}\n\nmessage GetUserResponse {\n  User user = 1;\n}\n```\n\n## Best Practices\n\n- ✅ **Do:** Use Buf to standardize your toolchain and linting with `buf.yaml` and `buf.gen.yaml`.\n- ✅ **Do:** Always use semantic versioning in package paths (e.g., `package api.v1`).\n- ✅ **Do:** Enforce mTLS for all internal service-to-service communication.\n- ✅ **Do:** Handle `ctx.Done()` in all streaming handlers to prevent resource leaks.\n- ✅ **Do:** Map domain errors to standard gRPC status codes (e.g., `codes.NotFound`).\n- ❌ **Don't:** Return raw internal error strings or stack traces to gRPC clients.\n- ❌ **Don't:** Create a new `grpc.ClientConn` per request; always reuse connections.\n\n## Troubleshooting\n\n- **Error: Inconsistent Gen**: If the generated code does not match the schema, run `buf generate` and verify the `go_package` option.\n- **Error: Context Deadline**: Check client timeouts and ensure the server is not blocking infinitely in streaming handlers.\n- **Error: mTLS Handshake**: Ensure the CA certificate is correctly added to the `x509.CertPool` on both client and server sides.\n\n## Limitations\n\n- Does not cover service mesh traffic routing (Istio/Linkerd configuration).\n- Does not cover gRPC-Web or browser-based gRPC integration.\n- Assumes Go 1.21+ and gRPC-Go v1.60+; older versions may have different APIs (e.g., `grpc.Dial` vs `grpc.NewClient`).\n- Does not cover L7 gRPC-aware load balancer configuration (e.g., Envoy, NGINX).\n- Does not address Protobuf schema registry or large-scale schema governance beyond Buf lint.\n\n## Resources\n\n- `resources/implementation-playbook.md` for detailed patterns, code examples, and anti-patterns.\n- [Google API Design Guide](https://cloud.google.com/apis/design)\n- [Buf Docs](https://buf.build/docs)\n- [gRPC-Go Docs](https://grpc.io/docs/languages/go/)\n- [OpenTelemetry Go Instrumentation](https://opentelemetry.io/docs/instrumentation/go/)\n\n## Related Skills\n\n- @golang-pro - General Go patterns and performance optimization outside the gRPC layer.\n- @go-concurrency-patterns - Advanced goroutine lifecycle management for streaming handlers.\n- @api-design-principles - Resource naming and versioning strategy before writing `.proto` files.\n- @docker-expert - Containerizing gRPC services and configuring TLS cert injection via Docker secrets.","tags":["grpc","golang","antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows"],"capabilities":["skill","source-sickn33","skill-grpc-golang","topic-agent-skills","topic-agentic-skills","topic-ai-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workflows","topic-antigravity","topic-antigravity-skills","topic-claude-code","topic-claude-code-skills","topic-codex-cli","topic-codex-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/grpc-golang","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sickn33/antigravity-awesome-skills","source_repo":"https://github.com/sickn33/antigravity-awesome-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 34768 github stars · SKILL.md body (4,300 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-23T18:51:25.747Z","embedding":null,"createdAt":"2026-04-18T21:38:19.462Z","updatedAt":"2026-04-23T18:51:25.747Z","lastSeenAt":"2026-04-23T18:51:25.747Z","tsv":"'/apis/design)':524 '/docs)':529 '/docs/instrumentation/go/)':542 '/docs/languages/go/)':536 '/org/repo/gen/api/v1;apiv1':272 '1':159,255,284,292,297 '1.21':463 '2':179,287 '3':193 '4':206 '5':217 '6':227 'abil':127 'ad':429 'address':494 'advanc':562 'alway':229,314,378 'anti':251,516 'anti-pattern':250,515 'api':83,93,117,132,261,474,519,570 'api-design-principl':569 'api.v1':200,266,323 'api.v2':135 'applic':151 'assum':461 'authent':106,216 'awar':485 'backward':138 'balanc':487 'base':458 'best':298 'beyond':504 'bidirect':91 'block':415 'break':234 'browser':457 'browser-bas':456 'buf':23,55,98,175,231,302,395,505,525 'buf.build':528 'buf.build/docs)':527 'buf.gen.yaml':312 'buf.yaml':310 'build':4,78,113 'ca':425 'cert':591 'certif':426 'chang':235 'check':236,406 'client':369,407,435 'cloud.google.com':523 'cloud.google.com/apis/design)':522 'code':152,239,247,354,388,512 'codes.notfound':356 'communic':73,334 'compat':139 'comprehens':38 'concurr':560 'configur':99,219,448,488,589 'confirm':160,180 'connect':380 'container':585 'context':162,404 'contract':21,52,94 'correct':428 'cover':51,442,451,481 'creat':372 'ctx.done':337 'deadlin':405 'deep':62 'defin':196,256 'design':19,41,71,208,520,571 'detail':245,510 'differ':473 'doc':526,533 'docker':583,594 'docker-expert':582 'domain':348 'e.g':134,145,199,321,355,475,489 'enforc':325 'ensur':137,410,423 'envoy':490 'error':204,349,362,382,403,420 'exampl':248,253,254,513 'expert':584 'file':124,581 'final':238 'gen':384 'general':548 'generat':240,387,396 'getus':276 'getuserrequest':277,289 'getuserrespons':279,294 'github.com':271 'github.com/org/repo/gen/api/v1;apiv1':270 'go':11,36,50,77,164,168,268,400,462,467,532,538,549,559 'go-concurrency-pattern':558 'golang':3,33,546 'golang-pro':545 'googl':518 'goroutin':563 'govern':503 'grade':46 'grpc':2,8,32,35,47,75,119,167,352,368,453,459,466,484,531,556,586 'grpc-awar':483 'grpc-go':34,166,465,530 'grpc-golang':1 'grpc-web':452 'grpc.clientconn':375 'grpc.dial':476 'grpc.io':535 'grpc.io/docs/languages/go/)':534 'grpc.newclient':478 'guid':39,158,521 'handl':336 'handler':341,419,568 'handshak':422 'high':80 'high-perform':79 'id':283,291 'identifi':163,182 'implement':25,43,86,209 'inconsist':383 'infinit':416 'inject':592 'instrument':539 'integr':460 'interceptor':66,220 'intern':82,329,361 'introduc':129 'istio/linkerd':146,447 'l7':482 'larg':500 'large-scal':499 'layer':57,557 'leak':345 'legaci':122 'lifecycl':564 'limit':192,439 'lint':232,308,506 'load':185,486 'log':226 'manag':140,565 'map':205,347 'match':391 'may':471 'mesh':142,444 'messag':190,259,280,288,293 'metric':223 'microservic':72 'modifi':121 'mtls':13,60,100,183,210,326,421 'name':286,574 'need':184 'new':131,374 'nginx':491 'observ':16,63,218 'older':469 'opentelemetri':65,537 'opentelemetry.io':541 'opentelemetry.io/docs/instrumentation/go/)':540 'optim':553 'option':267,402 'outsid':149,554 'overview':37 'packag':197,265,269,319,322,401 'path':320 'pattern':186,246,252,511,517,550,561 'per':376 'perform':81,552 'plan':194 'practic':299 'prevent':343 'principl':572 'pro':547 'product':6,45 'production-grad':44 'production-readi':5 'project':173 'proto':123,262,580 'proto3':264 'protobuf':20,85,96,495 'protoc':178 'public':116 'pure':114 'raw':177,360 'readi':7 'refer':241 'registri':497 'relat':543 'request':377 'requir':120,181 'resourc':201,344,507,573 'resources/implementation-playbook.md':243,508 'rest/http':115 'return':278,359 'reus':379 'rout':144,446 'rpc':275 'run':230,394 'scale':501 'schema':195,393,496,502 'scope':153 'secret':595 'secur':26,58,207 'semant':316 'server':412,437 'servic':9,28,30,48,103,105,141,213,215,258,273,331,333,443,587 'service-to-servic':27,102,212,330 'side':438 'size':191 'skill':69,111,544 'skill-grpc-golang' 'slos':188 'source-sickn33' 'stack':365 'standard':53,92,304,351 'status':353 'step':155,157 'step-by-step':154 'strategi':577 'stream':14,87,340,418,567 'string':282,285,290,363 'structur':225 'syntax':263 'technic':161 'timeout':408 'tls':590 'toolchain':306 'topic-agent-skills' 'topic-agentic-skills' 'topic-ai-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workflows' 'topic-antigravity' 'topic-antigravity-skills' 'topic-claude-code' 'topic-claude-code-skills' 'topic-codex-cli' 'topic-codex-skills' 'trace':222,366 'traffic':143,445 'transport':31,56 'troubleshoot':381 'type':202 'unary/streaming':187 'unidirect':89 'use':17,67,84,95,109,174,301,315 'user':281,295,296 'userservic':274 'v1':260 'v1.60':468 'verif':228 'verifi':398 'version':133,165,169,198,317,470,576 'via':59,593 'vs':477 'web':454 'whether':171 'without':118,125 'workload':88 'write':579 'x509.certpool':432","prices":[{"id":"9f210712-54b1-4b49-bed6-f77755d77fec","listingId":"80368a99-cc6e-40cb-94ae-170c7214ad35","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T21:38:19.462Z"}],"sources":[{"listingId":"80368a99-cc6e-40cb-94ae-170c7214ad35","source":"github","sourceId":"sickn33/antigravity-awesome-skills/grpc-golang","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/grpc-golang","isPrimary":false,"firstSeenAt":"2026-04-18T21:38:19.462Z","lastSeenAt":"2026-04-23T18:51:25.747Z"}],"details":{"listingId":"80368a99-cc6e-40cb-94ae-170c7214ad35","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"grpc-golang","github":{"repo":"sickn33/antigravity-awesome-skills","stars":34768,"topics":["agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity","antigravity-skills","claude-code","claude-code-skills","codex-cli","codex-skills","cursor","cursor-skills","developer-tools","gemini-cli","gemini-skills","kiro","mcp","skill-library"],"license":"mit","html_url":"https://github.com/sickn33/antigravity-awesome-skills","pushed_at":"2026-04-23T06:41:03Z","description":"Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.","skill_md_sha":"68d4136059da8351d9b13e608674825d1d7ccc5d","skill_md_path":"skills/grpc-golang/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/grpc-golang"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"name":"grpc-golang","description":"Build production-ready gRPC services in Go with mTLS, streaming, and observability. Use when designing Protobuf contracts with Buf or implementing secure service-to-service transport."},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/grpc-golang"},"updatedAt":"2026-04-23T18:51:25.747Z"}}