Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Expert guide for designing and building gRPC services including protobuf schema design, streaming patterns, interceptors, error handling, load balancing, and performance optimization across polyglot environments.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
400 lines · 1,365 words
You are an expert in designing and building high-performance gRPC services. You guide teams through protobuf schema design, service definition, streaming patterns, interceptor middleware, error handling, and production deployment of gRPC-based systems.
Schema-first design - Define your .proto files before writing any service code. The schema is the contract.
Expert guide for designing and building gRPC services including protobuf schema design, streaming patterns, interceptors, error handling, load balancing, and performance optimization across polyglot environments.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the gRPC Engineer skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
The principle
You are an expert in designing and building high-performance gRPC services. You guide teams through protobuf schema design, service definition, streaming patterns, interceptor middleware, error handling, and production deployment of gRPC-based systems.
What it covers
Core Principles
Protobuf Schema Design
Service Definition
Streaming Patterns
Interceptors (Middleware)
Error Handling
Performance Optimization
Code Generation with Buf
Health Checking and Reflection
Production Checklist
When to Use
Output Format
Example
Edge Cases
Streaming when appropriate - Use unary for simple request/response; streaming for real-time or large payloads.
syntax = "proto3";
package api.v1;
option go_package = "github.com/myorg/myapp/gen/api/v1;apiv1";
import "google/protobuf/timestamp.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/wrappers.proto";
message User {
// Field numbers 1-15 use 1 byte; reserve for frequently accessed fields
string id = 1;
string email = 2;
string display_name = 3;
UserRole role = 4;
UserStatus status = 5;
google.protobuf.Timestamp created_at = 10;
google.protobuf.Timestamp updated_at = 11;
google.protobuf.StringValue phone_number = 15; // Nullable
reserved 6, 8;
reserved "legacy_name", "old_email";
}
enum UserRole {
USER_ROLE_UNSPECIFIED = 0; // Always have UNSPECIFIED as 0
USER_ROLE_ADMIN = 1;
USER_ROLE_EDITOR = 2;
USER_ROLE_VIEWER = 3;
}SAFE (backward compatible):
- Add new fields with new field numbers
- Add new enum values (not position 0)
- Add new RPC methods or services
BREAKING (never do):
- Remove/rename a field or change its number/type
- Change enum value numbers
- Remove an RPC method or rename a package
WHEN YOU MUST BREAK:
- Create a new package version (api.v2)
- Run both versions during migrationservice UserService {
rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
rpc GetUser(GetUserRequest) returns (GetUserResponse);
rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);
rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse);
}
message ListUsersRequest {
int32 page_size = 1;
string page_token = 2; // Opaque cursor
string filter = 3;
string order_by = 4;
}
message ListUsersResponse {
repeated User users = 1;
string next_page_token = 2;
int32 total_count = 3;
}
message UpdateUserRequest {
User user = 1;
google.protobuf.FieldMask update_mask = 2;
}PATTERN USE CASE EXAMPLE
---------------------------------------------------------------------
Unary Simple request/response GetUser, CreateOrder
Server streaming Server pushes multiple items Subscribe, LargeExport
Client streaming Client sends multiple items FileUpload, BatchInsert
Bidirectional Both sides push messages Chat, LiveDashboardfunc (s *server) SubscribeEvents(req *pb.SubscribeRequest, stream pb.Service_SubscribeEventsServer) error {
ch := s.eventBus.Subscribe(req.Topics)
defer s.eventBus.Unsubscribe(ch)
for {
select {
case event := <-ch:
if err := stream.Send(event); err != nil {
return status.Errorf(codes.Internal, "send failed: %v", err)
}
case <-stream.Context().Done():
return nil
}
}
}func (s *server) UploadFile(stream pb.Service_UploadFileServer) error {
var buf bytes.Buffer
for {
chunk, err := stream.Recv()
if err == io.EOF {
return stream.SendAndClose(&pb.UploadResponse{
BytesReceived: int64(buf.Len()),
})
}
if err != nil {
return err
}
buf.Write(chunk.Data)
}
}server := grpc.NewServer(
grpc.ChainUnaryInterceptor(
recoveryInterceptor, // 1. Panic recovery (outermost)
requestIDInterceptor, // 2. Request ID injection
loggingInterceptor, // 3. Request/response logging
metricsInterceptor, // 4. Prometheus metrics
authInterceptor, // 5. Authentication
validationInterceptor, // 6. Request validation
),
grpc.ChainStreamInterceptor(
streamRecoveryInterceptor,
streamLoggingInterceptor,
streamAuthInterceptor,
),
)func authInterceptor(
ctx context.Context, req interface{},
info *grpc.UnaryServerInfo, handler grpc.UnaryHandler,
) (interface{}, error) {
if info.FullMethod == "/grpc.health.v1.Health/Check" {
return handler(ctx, req)
}
md, ok := metadata.FromIncomingContext(ctx)
if !ok {
return nil, status.Error(codes.Unauthenticated, "missing metadata")
}
tokens := md.Get("authorization")
if len(tokens) == 0 {
return nil, status.Error(codes.Unauthenticated, "missing token")
}
claims, err := validateToken(tokens[0])
if err != nil {
return nil, status.Errorf(codes.Unauthenticated, "invalid token: %v", err)
}
ctx = context.WithValue(ctx, claimsKey, claims)
return handler(ctx, req)
}CODE WHEN TO USE
-----------------------------------------------------------
INVALID_ARGUMENT (3) Client sent bad input (validation)
NOT_FOUND (5) Resource does not exist
ALREADY_EXISTS (6) Duplicate resource creation
PERMISSION_DENIED (7) Authenticated but not authorized
UNAUTHENTICATED (16) Missing or invalid credentials
RESOURCE_EXHAUSTED (8) Rate limit or quota exceeded
FAILED_PRECONDITION (9) System not in required state
ABORTED (10) Concurrency conflict (retry)
INTERNAL (13) Internal server error
UNAVAILABLE (14) Temporarily unavailable (retry)func validateCreateUser(req *pb.CreateUserRequest) error {
var violations []*errdetails.BadRequest_FieldViolation
if req.Email == "" {
violations = append(violations, &errdetails.BadRequest_FieldViolation{
Field: "email", Description: "Email is required",
})
}
if len(violations) > 0 {
st := status.New(codes.InvalidArgument, "validation failed")
detailed, _ := st.WithDetails(&errdetails.BadRequest{FieldViolations: violations})
return detailed.Err()
}
return nil
}conn, _ := grpc.Dial(target,
grpc.WithTransportCredentials(creds),
grpc.WithKeepaliveParams(keepalive.ClientParameters{
Time: 10 * time.Second, Timeout: 3 * time.Second,
PermitWithoutStream: true,
}),
grpc.WithDefaultCallOptions(
grpc.MaxCallRecvMsgSize(10*1024*1024),
grpc.MaxCallSendMsgSize(10*1024*1024),
),
)CLIENT-SIDE (service-to-service):
round_robin, pick_first, or custom weighted
conn, _ := grpc.Dial("dns:///service:50051",
grpc.WithDefaultServiceConfig(`{"loadBalancingPolicy":"round_robin"}`))
PROXY-BASED (external clients):
Envoy: full gRPC-aware L7 proxy
Cloud LBs: GCP has native gRPC support# buf.gen.yaml
version: v2
plugins:
- remote: buf.build/protocolbuffers/go
out: gen
opt: paths=source_relative
- remote: buf.build/grpc/go
out: gen
opt: paths=source_relativebuf lint # Lint protos
buf breaking --against '.git#branch=main' # Check breaking changes
buf generate # Generate codeimport "google.golang.org/grpc/health"
import healthpb "google.golang.org/grpc/health/grpc_health_v1"
healthServer := health.NewServer()
healthpb.RegisterHealthServer(grpcServer, healthServer)
healthServer.SetServingStatus("api.v1.UserService", healthpb.HealthCheckResponse_SERVING)
// Reflection (dev/staging only)
reflection.Register(grpcServer)grpcurl -plaintext localhost:50051 list
grpcurl -plaintext -d '{"id":"user_123"}' localhost:50051 api.v1.UserService/GetUserSCHEMA:
[ ] All enums have UNSPECIFIED = 0 value
[ ] Reserved fields for any removed fields
[ ] buf lint and breaking change detection in CI
SERVICE:
[ ] Health check endpoint registered
[ ] Interceptor chain: recovery > logging > metrics > auth > validation
[ ] Deadlines propagated across service boundaries
[ ] Graceful shutdown implemented
PERFORMANCE:
[ ] Keepalive configured on client and server
[ ] Max message size set appropriately
[ ] Client-side load balancing configured
SECURITY:
[ ] TLS enabled in production (never plaintext)
[ ] Auth interceptor on all non-health RPCs
[ ] Reflection disabled in production
[ ] Input validation on all request messagesUse this skill when:
Designing or implementing grpc engineer solutions
Reviewing or improving existing grpc engineer approaches
Making architectural or implementation decisions about grpc engineer
Learning grpc engineer patterns and best practices
Troubleshooting grpc engineer-related issues
Do NOT use this skill when:
The question is about a fundamentally different technology domain
A more specific sibling skill covers the exact topic needed
The user needs a complete hands-on tutorial rather than expert guidance
# Grpc Engineer Analysis
## Context Assessment
[Situation summary and constraints]
## Recommended Approach
[Primary recommendation with rationale]
## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]
## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]
## Next Steps
- [Immediate action item]
- [Follow-up action item]Input: "Help me implement grpc engineer for a medium-scale production application"
Output: A structured analysis covering current state assessment, recommended grpc engineer approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.
Legacy system integration: When grpc engineer must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities
SKILL.md
400 lines · 1,365 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
gRPC Engineer bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for