# Grpc Golang

> 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.

- Skill: `techwavedev/grpc-golang` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add techwavedev/grpc-golang`
- Raw SKILL.md: https://api.skillmd.com/api/skills/techwavedev/grpc-golang/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: techwavedev (https://skillmd.com/u/techwavedev)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/techwavedev/grpc-golang

---


# gRPC Golang (gRPC-Go)

## Overview

Comprehensive 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.

## Use this skill when

- Designing microservices communication with gRPC in Go.
- Building high-performance internal APIs using Protobuf.
- Implementing streaming workloads (unidirectional or bidirectional).
- Standardizing API contracts using Protobuf and Buf.
- Configuring mTLS for service-to-service authentication.

## Do not use this skill when

- Building pure REST/HTTP public APIs without gRPC requirements.
- Modifying legacy `.proto` files without the ability to introduce a new API version (e.g., `api.v2`) or ensure backward compatibility.
- Managing service mesh traffic routing (e.g., Istio/Linkerd), which is outside the application code scope.

## Step-by-Step Guide

1. **Confirm Technical Context**: Identify Go version, gRPC-Go version, and whether the project uses Buf or raw protoc.
2. **Confirm Requirements**: Identify mTLS needs, load patterns (unary/streaming), SLOs, and message size limits.
3. **Plan Schema**: Define package versioning (e.g., `api.v1`), resource types, and error mapping.
4. **Security Design**: Implement mTLS for service-to-service authentication.
5. **Observability**: Configure interceptors for tracing, metrics, and structured logging.
6. **Verification**: Always run `buf lint` and breaking change checks before finalizing code generation.

Refer to `resources/implementation-playbook.md` for detailed patterns, code examples, and anti-patterns.

## Examples

### Example 1: Defining a Service & Message (v1 API)

```proto
syntax = "proto3";
package api.v1;
option go_package = "github.com/org/repo/gen/api/v1;apiv1";

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
}

message User {
  string id = 1;
  string name = 2;
}

message GetUserRequest {
  string id = 1;
}

message GetUserResponse {
  User user = 1;
}
```

## Best Practices

- ✅ **Do:** Use Buf to standardize your toolchain and linting with `buf.yaml` and `buf.gen.yaml`.
- ✅ **Do:** Always use semantic versioning in package paths (e.g., `package api.v1`).
- ✅ **Do:** Enforce mTLS for all internal service-to-service communication.
- ✅ **Do:** Handle `ctx.Done()` in all streaming handlers to prevent resource leaks.
- ✅ **Do:** Map domain errors to standard gRPC status codes (e.g., `codes.NotFound`).
- ❌ **Don't:** Return raw internal error strings or stack traces to gRPC clients.
- ❌ **Don't:** Create a new `grpc.ClientConn` per request; always reuse connections.

## Troubleshooting

- **Error: Inconsistent Gen**: If the generated code does not match the schema, run `buf generate` and verify the `go_package` option.
- **Error: Context Deadline**: Check client timeouts and ensure the server is not blocking infinitely in streaming handlers.
- **Error: mTLS Handshake**: Ensure the CA certificate is correctly added to the `x509.CertPool` on both client and server sides.

## Limitations

- Does not cover service mesh traffic routing (Istio/Linkerd configuration).
- Does not cover gRPC-Web or browser-based gRPC integration.
- Assumes Go 1.21+ and gRPC-Go v1.60+; older versions may have different APIs (e.g., `grpc.Dial` vs `grpc.NewClient`).
- Does not cover L7 gRPC-aware load balancer configuration (e.g., Envoy, NGINX).
- Does not address Protobuf schema registry or large-scale schema governance beyond Buf lint.

## Resources

- `resources/implementation-playbook.md` for detailed patterns, code examples, and anti-patterns.
- [Google API Design Guide](https://cloud.google.com/apis/design)
- [Buf Docs](https://buf.build/docs)
- [gRPC-Go Docs](https://grpc.io/docs/languages/go/)
- [OpenTelemetry Go Instrumentation](https://opentelemetry.io/docs/instrumentation/go/)

## Related Skills

- @golang-pro - General Go patterns and performance optimization outside the gRPC layer.
- @go-concurrency-patterns - Advanced goroutine lifecycle management for streaming handlers.
- @api-design-principles - Resource naming and versioning strategy before writing `.proto` files.
- @docker-expert - Containerizing gRPC services and configuring TLS cert injection via Docker secrets.

---

<!-- AGI-INTEGRATION-START -->

## AGI Framework Integration

> **Adapted for [@techwavedev/agi-agent-kit](https://www.npmjs.com/package/@techwavedev/agi-agent-kit)**
> Original source: [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills)

### Memory-First Protocol

Retrieve prior design decisions (color palettes, typography, spacing scales) to maintain visual consistency across sessions. Cache generated design tokens.

```bash
# Check for prior frontend/design context before starting
python3 execution/memory_manager.py auto --query "design system decisions and component patterns for Grpc Golang"
```

### Storing Results

After completing work, store frontend/design decisions for future sessions:

```bash
python3 execution/memory_manager.py store \
  --content "Design system: adopted 8px grid, Inter font family, HSL color tokens with dark mode support" \
  --type decision --project <project> \
  --tags grpc-golang frontend
```

### Multi-Agent Collaboration

Share design decisions with backend agents (API contract changes) and QA agents (visual regression baselines).

```bash
python3 execution/cross_agent_context.py store \
  --agent "<your-agent>" \
  --action "Implemented UI components — new design system with accessibility compliance (WCAG 2.1 AA)" \
  --project <project>
```

### Design Memory Persistence

Store design system tokens and component decisions in Qdrant so any agent on any platform (Claude, Gemini, Cursor) can retrieve and apply consistent styling.

<!-- AGI-INTEGRATION-END -->