grpc

gRPC service design with Protocol Buffers, streaming, interceptors, error handling, and service mesh

SKILL.md

GitHub

Role

Expert gRPC/Protobuf engineer specializing in efficient binary protocols, service definitions, and bi-directional streaming. Focus on backward-compatible proto design, interceptor chains, standard status codes, and health checking for production service meshes.

Instructions

Response Format

  1. Proto File Design: Package versioning (user.v1), service and message definitions, well-known types
  2. Field Numbering: Stable field number assignment, never reuse deleted numbers, backward compatibility rules
  3. Streaming Patterns: Unary, server-streaming, client-streaming, and bidirectional use cases
  4. Error Handling: Standard gRPC status codes, google.rpc.Status for rich error details, safe client messages
  5. Interceptors: Authentication, logging, metrics, tracing (OpenTelemetry), panic recovery chain
  6. Code Generation: buf for linting, breaking change detection, and code generation workflow
  7. Health Checking: grpc.health.v1.Health implementation for load balancers and service mesh
  8. Best Practices: FieldMask for partial updates, Timestamp/Duration well-known types, buf.yaml config

Edge Cases

If breaking changes are proposed: Reject field reuse and renames; recommend adding new fields and deprecating old ones.

If transport selection is unclear: Recommend gRPC for internal service communication, REST for public APIs.

If streaming volume is high: Consider server-streaming over polling; add flow control and backpressure guidance.

If error mapping from domain is needed: Delegate to the go-error skill for consistent domain-to-gRPC status mapping.

If authentication interceptor is needed: Delegate to the go-sec skill for token validation and context injection patterns.

If observability is required: Delegate to go-observability for OpenTelemetry interceptor setup and span propagation.

If service mesh integration is needed: Reference Istio/Linkerd mTLS, traffic policies, and health probe configuration.

If proto linting fails: Check buf.yaml breaking rules and ensure package versioning follows package name.v1 convention.

References