Generating gRPC Services
Overview
Generate gRPC service definitions, client/server stubs, and implementations from Protocol Buffer (protobuf) .proto files. Scaffold unary, server-streaming, client-streaming, and bidirectional-streaming RPC methods with proper error status codes, interceptors for auth/logging, and health check service registration.
Prerequisites
- Protocol Buffers compiler (
protoc) v3.21+ installed
- Language-specific gRPC plugin:
grpc_tools_node_protoc_plugin (Node.js), grpcio-tools (Python), or Go gRPC plugin
buf CLI for proto linting and breaking change detection (recommended)- gRPC testing tool:
grpcurl, evans, or BloomRPC
- TLS certificates for production transport security (mTLS recommended for service-to-service)
Instructions
- Read existing
.proto files using Glob and Read, or design new service definitions with message types, RPC methods, and streaming patterns per service requirements.
- Define proto3 message types with appropriate field types, using
google.protobuf.Timestamp for dates, google.protobuf.Struct for dynamic fields, and oneof for polymorphic messages.
- Compile
.proto files with protoc to generate language-specific stubs, server interfaces, and client libraries using the appropriate gRPC plugin.
- Implement server-side RPC handlers for each method, returning proper gRPC status codes (
OK, NOT_FOUND, INVALID_ARGUMENT, PERMISSION_DENIED) instead of generic errors.
- Add server interceptors for authentication (extracting JWT from metadata), request logging with correlation IDs, and deadline propagation across service calls.
- Implement health check service (
grpc.health.v1.Health) and reflection service for runtime introspection by tools like grpcurl.
- Configure TLS transport security, preferring mutual TLS (mTLS) for service-to-service communication with certificate rotation support.
- Write integration tests using an in-process test server, validating all RPC methods including streaming scenarios with multiple messages and error conditions.
- Generate a REST-to-gRPC gateway using
grpc-gateway annotations for HTTP/JSON clients that need to access gRPC services.
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDE_SKILL_DIR}/proto/ - Protocol Buffer service and message definitions${CLAUDE_SKILL_DIR}/generated/ - Auto-generated stubs and client/server code${CLAUDE_SKILL_DIR}/src/services/ - RPC method handler implementations${CLAUDE_SKILL_DIR}/src/interceptors/ - Auth, logging, and metrics interceptors${CLAUDE_SKILL_DIR}/src/health/ - Health check service implementation${CLAUDE_SKILL_DIR}/gateway/ - REST-to-gRPC gateway configuration (optional)${CLAUDE_SKILL_DIR}/tests/ - Integration tests with in-process test server
Error Handling
| Error |
Cause |
Solution |
| INVALID_ARGUMENT (3) |
Request message fails field validation constraints |
Return detailed BadRequest error details with field-level violation descriptions |
| NOT_FOUND (5) |
Requested resource does not exist |
Include resource type and ID in error message metadata for client debugging |
| PERMISSION_DENIED (7) |
Caller lacks required role or scope in JWT metadata |
Return required permission in error details; log denied access attempt |
| DEADLINE_EXCEEDED (4) |
RPC took longer than client-specified deadline |
Propagate deadlines to downstream calls; implement cascading timeout budgets |
| UNAVAILABLE (14) |
Server overloaded or downstream dependency unreachable |
Client should retry with exponential backoff; server should implement backpressure |
Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.
Examples
User management service: Define UserService with CreateUser, GetUser, ListUsers (server-streaming for large result sets), and UpdateUser RPCs with field mask support for partial updates.
Real-time event stream: Bidirectional streaming RPC where clients subscribe to event topics and the server pushes filtered events, with flow control via client-side backpressure signals.
gRPC-Web frontend: Generate gRPC-Web compatible stubs for browser clients using Envoy proxy for HTTP/2 to gRPC translation, enabling direct proto-based communication from React/Vue applications.
See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.
Resources
1---2name: generating-grpc-services3description: Generate gRPC service definitions, stubs, and implementations from Protocol Buffers. Use when creating high-performance gRPC services. Trigger with phrases like "generate gRPC service", "create gRPC API", or "build gRPC server".4license: MIT5---6# Generating gRPC Services78## Overview910Generate gRPC service definitions, client/server stubs, and implementations from Protocol Buffer (protobuf) `.proto` files. Scaffold unary, server-streaming, client-streaming, and bidirectional-streaming RPC methods with proper error status codes, interceptors for auth/logging, and health check service registration.1112## Prerequisites1314- Protocol Buffers compiler (`protoc`) v3.21+ installed15- Language-specific gRPC plugin: `grpc_tools_node_protoc_plugin` (Node.js), `grpcio-tools` (Python), or Go gRPC plugin16- `buf` CLI for proto linting and breaking change detection (recommended)17- gRPC testing tool: `grpcurl`, `evans`, or BloomRPC18- TLS certificates for production transport security (mTLS recommended for service-to-service)1920## Instructions21221. Read existing `.proto` files using Glob and Read, or design new service definitions with message types, RPC methods, and streaming patterns per service requirements.232. Define proto3 message types with appropriate field types, using `google.protobuf.Timestamp` for dates, `google.protobuf.Struct` for dynamic fields, and `oneof` for polymorphic messages.243. Compile `.proto` files with `protoc` to generate language-specific stubs, server interfaces, and client libraries using the appropriate gRPC plugin.254. Implement server-side RPC handlers for each method, returning proper gRPC status codes (`OK`, `NOT_FOUND`, `INVALID_ARGUMENT`, `PERMISSION_DENIED`) instead of generic errors.265. Add server interceptors for authentication (extracting JWT from metadata), request logging with correlation IDs, and deadline propagation across service calls.276. Implement health check service (`grpc.health.v1.Health`) and reflection service for runtime introspection by tools like `grpcurl`.287. Configure TLS transport security, preferring mutual TLS (mTLS) for service-to-service communication with certificate rotation support.298. Write integration tests using an in-process test server, validating all RPC methods including streaming scenarios with multiple messages and error conditions.309. Generate a REST-to-gRPC gateway using `grpc-gateway` annotations for HTTP/JSON clients that need to access gRPC services.3132See `${CLAUDE_SKILL_DIR}/references/implementation.md` for the full implementation guide.3334## Output3536- `${CLAUDE_SKILL_DIR}/proto/` - Protocol Buffer service and message definitions37- `${CLAUDE_SKILL_DIR}/generated/` - Auto-generated stubs and client/server code38- `${CLAUDE_SKILL_DIR}/src/services/` - RPC method handler implementations39- `${CLAUDE_SKILL_DIR}/src/interceptors/` - Auth, logging, and metrics interceptors40- `${CLAUDE_SKILL_DIR}/src/health/` - Health check service implementation41- `${CLAUDE_SKILL_DIR}/gateway/` - REST-to-gRPC gateway configuration (optional)42- `${CLAUDE_SKILL_DIR}/tests/` - Integration tests with in-process test server4344## Error Handling4546| Error | Cause | Solution |47|-------|-------|----------|48| INVALID_ARGUMENT (3) | Request message fails field validation constraints | Return detailed `BadRequest` error details with field-level violation descriptions |49| NOT_FOUND (5) | Requested resource does not exist | Include resource type and ID in error message metadata for client debugging |50| PERMISSION_DENIED (7) | Caller lacks required role or scope in JWT metadata | Return required permission in error details; log denied access attempt |51| DEADLINE_EXCEEDED (4) | RPC took longer than client-specified deadline | Propagate deadlines to downstream calls; implement cascading timeout budgets |52| UNAVAILABLE (14) | Server overloaded or downstream dependency unreachable | Client should retry with exponential backoff; server should implement backpressure |5354Refer to `${CLAUDE_SKILL_DIR}/references/errors.md` for comprehensive error patterns.5556## Examples5758**User management service**: Define `UserService` with `CreateUser`, `GetUser`, `ListUsers` (server-streaming for large result sets), and `UpdateUser` RPCs with field mask support for partial updates.5960**Real-time event stream**: Bidirectional streaming RPC where clients subscribe to event topics and the server pushes filtered events, with flow control via client-side backpressure signals.6162**gRPC-Web frontend**: Generate gRPC-Web compatible stubs for browser clients using Envoy proxy for HTTP/2 to gRPC translation, enabling direct proto-based communication from React/Vue applications.6364See `${CLAUDE_SKILL_DIR}/references/examples.md` for additional examples.6566## Resources6768- gRPC documentation: https://grpc.io/docs/69- Protocol Buffers Language Guide: https://protobuf.dev/programming-guides/proto3/70- Buf CLI for proto management: https://buf.build/71- gRPC-Gateway: https://grpc-ecosystem.github.io/grpc-gateway/
jeremylongshore