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 Services
7
8## Overview
9
10Generate 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.
11
12## Prerequisites
13
14- Protocol Buffers compiler (`protoc`) v3.21+ installed
15- Language-specific gRPC plugin: `grpc_tools_node_protoc_plugin` (Node.js), `grpcio-tools` (Python), or Go gRPC plugin
16- `buf` CLI for proto linting and breaking change detection (recommended)
17- gRPC testing tool: `grpcurl`, `evans`, or BloomRPC
18- TLS certificates for production transport security (mTLS recommended for service-to-service)
19
20## Instructions
21
221. 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.
31
32See `${CLAUDE_SKILL_DIR}/references/implementation.md` for the full implementation guide.
33
34## Output
35
36- `${CLAUDE_SKILL_DIR}/proto/` - Protocol Buffer service and message definitions
37- `${CLAUDE_SKILL_DIR}/generated/` - Auto-generated stubs and client/server code
38- `${CLAUDE_SKILL_DIR}/src/services/` - RPC method handler implementations
39- `${CLAUDE_SKILL_DIR}/src/interceptors/` - Auth, logging, and metrics interceptors
40- `${CLAUDE_SKILL_DIR}/src/health/` - Health check service implementation
41- `${CLAUDE_SKILL_DIR}/gateway/` - REST-to-gRPC gateway configuration (optional)
42- `${CLAUDE_SKILL_DIR}/tests/` - Integration tests with in-process test server
43
44## Error Handling
45
46| 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 |
53
54Refer to `${CLAUDE_SKILL_DIR}/references/errors.md` for comprehensive error patterns.
55
56## Examples
57
58**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.
59
60**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.
61
62**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.
63
64See `${CLAUDE_SKILL_DIR}/references/examples.md` for additional examples.
65
66## Resources
67
68- 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/
gabrielmoreira