Skip to main content
skill CX Codex

grpc-expert — Claude Code skill: what it does, how to install

grpc-expert walks the agent through gRPC work: protobuf schemas, the four RPC styles, status codes, and the operational pieces such as load balancing and health checks.

Apache-2.0 182 installs ★ 45 updated 2026-10-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add personamanagmentlayer/pcl --skill grpc-expert -a claude-code
Open on GitHub

What grpc-expert does

Installs a gRPC frame of reference for the agent: protobuf schemas, service definitions, the four call types from plain unary through bidirectional streaming, HTTP/2 as transport, codegen and interceptors. Deadlines and status codes get their own sections, as does the operational side — load balancing, health checks, TLS, retry policies.

The skill ships concrete scaffolding. A .proto file defines UserService with every RPC shape, and there are server implementations in Python (thread pool behind grpc.server, listening on [::]:50051) and Go (grpc.NewServer on :50051). Treat them as a starting point, not something to copy blind.

One catch: allowed-tools stops at Read, Write, Edit. The skill cannot shell out, so protoc runs and builds stay with you — it writes the schema and the handler, you compile.

What it helps with

  • Define a .proto contract with unary and streaming methods
  • Stand up a Python gRPC server on a thread pool
  • Map failures to proper status codes and deadlines
  • Add health checks and retry policies before shipping
  • Port a Python handler to Go without touching the contract

Example prompts for the agent

  • Sketch a proto3 UserService with unary GetUser and server-streaming ListUsers
  • My calls keep hitting DEADLINE_EXCEEDED — walk through timeout handling on the server side
  • Port this gRPC server from Python to Go and keep the user.v1 contract intact

How to install grpc-expert

1Skills CLI (Vercel)

npx skills add personamanagmentlayer/pcl --skill grpc-expert -a claude-code

2Manually: put the files in place

~/.claude/skills/grpc-expert/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/grpc-expert/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about grpc-expert

How do I install grpc-expert in Claude Code?

Run npx skills add personamanagmentlayer/pcl --skill grpc-expert -a claude-code. The skill then sits at ~/.claude/skills/grpc-expert/SKILL.md.

What does grpc-expert do?

It gives the agent gRPC guidance: Protocol Buffers schemas, the RPC styles, status codes and deadlines, plus production concerns like load balancing and retries.

Will it compile my protos?

No. allowed-tools covers Read, Write and Edit, so the skill produces schemas and server code while running protoc and building the project is on you.

Source text

SKILL.md · Apache-2.0
---
name: grpc-expert
version: 1.1.0
description: >-
  Expert-level gRPC, Protocol Buffers, microservices communication, and streaming. Use when
  the user mentions Protocol Buffers, microservices, RPC, or streaming, or when the task
  involves gRPC Fundamentals, Communication Patterns, or Production Features.
category: api
tags: [grpc, protobuf, microservices, rpc, streaming]
allowed-tools:
  - Read
  - Write
  - Edit
---

# gRPC Expert

Expert guidance for gRPC services, Protocol Buffers, microservices communication, and streaming patterns.

## Core Concepts

### gRPC Fundamentals

- Protocol Buffers (protobuf)
- Service definitions
- RPC patterns (unary, server streaming, client streaming, bidirectional)
- HTTP/2 transport
- Code generation
- Interceptors and middleware

### Communication Patterns

- Unary RPC (request-response)
- Server streaming RPC
- Client streaming RPC
- Bidirectional streaming RPC
- Deadline/timeout handling
- Error handling and status codes

### Production Features

- Load balancing
- Service discovery
- Health checking
- Authentication (TLS, tokens)
- Monitoring and tracing
- Retry policies

## Protocol Buffer Definition

```protobuf
syntax = "proto3";

package user.v1;

import "google/protobuf/timestamp.proto";

service UserService {
  // Unary RPC
  rpc GetUser(GetUserRequest) returns (GetUserResponse);

  // Server streaming
  rpc ListUsers(ListUsersRequest) returns (stream User);

  // Client streaming
  rpc CreateUsers(stream CreateUserRequest) returns (CreateUsersResponse);

  // Bidirectional streaming
  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

message User {
  string id = 1;
  string email = 2;
  string name = 3;
  google.protobuf.Timestamp created_at = 4;
  UserRole role = 5;
}

enum UserRole {
  USER_ROLE_UNSPECIFIED = 0;
  USER_ROLE_USER = 1;
  USER_ROLE_ADMIN = 2;
}

message GetUserRequest {
  string id = 1;
}

message GetUserResponse {
  User user = 1;
}

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
}

message CreateUserRequest {
  string email = 1;
  string name = 2;
}

message CreateUsersResponse {
  repeated string user_ids = 1;
  int32 created_count = 2;
}

message ChatMessage {
  string user_id = 1;
  string message = 2;
  google.protobuf.Timestamp timestamp = 3;
}
```

## Python gRPC Server

```python
import grpc
from concurrent import futures
import logging
from typing import Iterator

import user_pb2
import user_pb2_grpc

class UserService(user_pb2_grpc.UserServiceServicer):
    def __init__(self):
        self.users = {}

    def GetUser(self, request, context):
        """Unary RPC"""
        user_id = request.id

        if user_id not in self.users:
            context.abort(grpc.StatusCode.NOT_FOUND, f"User {user_id} not found")

        user = self.users[user_id]
        return user_pb2.GetUserResponse(user=user)

    def ListUsers(self, request, context):
        """Server streaming RPC"""
        page_size = request.page_size or 10

        for i, user in enumerate(self.users.values()):
            if i >= page_size:
                break
            yield user

    def CreateUsers(self, request_iterator, context):
        """Client streaming RPC"""
        created_ids = []

        for request in request_iterator:
            user_id = self._generate_id()
            user = user_pb2.User(
                id=user_id,
                email=request.email,
                name=request.name
            )
            self.users[user_id] = user
            created_ids.append(user_id)

        return user_pb2.CreateUsersResponse(
            user_ids=created_ids,
            created_count=len(created_ids)
        )

    def Chat(self, request_iterator, context):
        """Bidirectional streaming RPC"""
        for message in request_iterator:
            # Echo back with modification
            response = user_pb2.ChatMessage(
                user_id="server",
                message=f"Echo: {message.message}",
                timestamp=message.timestamp
            )
            yield response

def serve():
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    user_pb2_grpc.add_UserServiceServicer_to_server(UserService(), server)

    server.add_insecure_port('[::]:50051')
    server.start()
    print("Server started on port 50051")
    server.wait_for_termination()

if __name__ == '__main__':
    logging.basicConfig()
    serve()
```

## Go gRPC Server

```go
package main

import (
    "context"
    "io"
    "log"
    "net"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
    pb "example.com/user/v1"
)

type userServer struct {
    pb.UnimplementedUserServiceServer
    users map[string]*pb.User
}

func (s *userServer) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.GetUserResponse, error) {
    user, exists := s.users[req.Id]
    if !exists {
        return nil, status.Errorf(codes.NotFound, "user %s not found", req.Id)
    }

    return &pb.GetUserResponse{User: user}, nil
}

func (s *userServer) ListUsers(req *pb.ListUsersRequest, stream pb.UserService_ListUsersServer) error {
    pageSize := req.PageSize
    if pageSize == 0 {
        pageSize = 10
    }

    count := 0
    for _, user := range s.users {
        if count >= int(pageSize) {
            break
        }

        if err := stream.Send(user); err != nil {
            return err
        }
        count++
    }

    return nil
}

func (s *userServer) CreateUsers(stream pb.UserService_CreateUsersServer) error {
    var userIds []string

    for {
        req, err := stream.Recv()
        if err == io.EOF {
            return stream.SendAndClose(&pb.CreateUsersResponse{
                UserIds:      userIds,
                CreatedCount: int32(len(userIds)),
            })
        }
        if err != nil {
            return err
        }

        userId := generateID()
        user := &pb.User{
            Id:    userId,
            Email: req.Email,
            Name:  req.Name,
        }

        s.users[userId] = user
        userIds = append(userIds, userId)
    }
}

func (s *userServer) Chat(stream pb.UserService_ChatServer) error {
    for {
        msg, err := stream.Recv()
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }

        response := &pb.ChatMessage{
            UserId:    "server",
            Message:   "Echo: " + msg.Message,
            Timestamp: msg.Timestamp,
        }

        if err := stream.Send(response); err != nil {
            return err
        }
    }
}

func main() {
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("failed to listen: %v", err)
    }

    s := grpc.NewServer()
    pb.RegisterUserServiceServer(s, &userServer{
        users: make(map[string]*pb.User),
    })

    log.Println("Server listening on :50051")
    if err := s.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}
```

## gRPC Client with Interceptors

```python
import grpc
import user_pb2
import user_pb2_grpc
from typing import Callable

def logging_interceptor(
    method: Callable,
    request,
    call_details: grpc.ClientCallDetails
):
    """Unary-unary interceptor for logging"""
    print(f"Calling method: {call_details.method}")
    print(f"Request: {request}")

    response = method(request, call_details)

    print(f"Response: {response}")
    return response

class UserClient:
    def __init__(self, host: str = 'localhost:50051'):
        # Create channel with interceptor
        self.channel = grpc.insecure_channel(host)
        self.channel = grpc.intercept_channel(
            self.channel,
            logging_interceptor
        )
        self.stub = user_pb2_grpc.UserServiceStub(self.channel)

    def get_user(self, user_id: str) -> user_pb2.User:
        """Call unary RPC"""
        request = user_pb2.GetUserRequest(id=user_id)

        try:
            response = self.stub.GetUser(
                request,
                timeout=5.0  # 5 second timeout
            )
            return response.user
        except grpc.RpcError as e:
            print(f"RPC failed: {e.code()} - {e.details()}")
            raise

    def list_users(self, page_size: int = 10):
        """Call server streaming RPC"""
        request = user_pb2.ListUsersRequest(page_size=page_size)

        try:
            for user in self.stub.ListUsers(request):
                yield user
        except grpc.RpcError as e:
            print(f"RPC failed: {e.code()} - {e.details()}")

    def create_users_batch(self, users: list):
        """Call client streaming RPC"""
        def request_generator():
            for user in users:
                yield user_pb2.CreateUserRequest(
                    email=user['email'],
                    name=user['name']
                )

        try:
            response = self.stub.CreateUsers(request_generator())
            return response
        except grpc.RpcError as e:
            print(f"RPC failed: {e.code()} - {e.details()}")

    def close(self):
        self.channel.close()
```

## Best Practices

### Design

- Use semantic versioning for protobuf packages
- Design backward-compatible changes
- Use proper field numbering (never reuse)
- Include metadata in messages
- Use enums with explicit UNSPECIFIED value
- Design for pagination in list operations

### Performance

- Enable HTTP/2 connection pooling
- Use streaming for large data transfers
- Implement proper timeouts
- Use compression for large payloads
- Batch operations when possible
- Monitor and tune thread pool sizes

### Production

- Implement health checks
- Use TLS for secure communication
- Add authentication/authorization
- Implement retry policies with backoff
- Monitor gRPC metrics (latency, errors)
- Use service discovery for dynamic endpoints

## Anti-Patterns

❌ Breaking backward compatibility
❌ No timeout configuration
❌ Ignoring error status codes
❌ Not handling stream cancellation
❌ Over-sized messages
❌ No health checking
❌ Missing authentication

## Resources

- gRPC: https://grpc.io/
- Protocol Buffers: https://protobuf.dev/
- gRPC-Go: https://github.com/grpc/grpc-go
- gRPC-Python: https://grpc.io/docs/languages/python/

© personamanagmentlayer · Apache-2.0 · personamanagmentlayer/pcl

Similar skills

All skills for Backend and APIs →

From the same set104

The whole set →
typescript-expert typescript-expert — a skill for expert-level TypeScript 5.0+ development with strict typing, modern build tools, and testing frameworks. CX Codex +1 187installs ai-architect-expert ai-architect-expert — a skill for AI system design: training pipelines, feature stores, model registries and serving with metrics. Useful when a prototype outgrows the notebook. CX Codex +1 185installs qa-expert qa-expert — a skill for test automation, QA strategy, and defect management across Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. CX Codex +1 184installs istio-expert The istio-expert skill helps manage Istio traffic, mTLS, and observability in Kubernetes. Use it to inspect a mesh or work through access policies. CX Codex +1 184installs media-expert media-expert — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that gives the agent deep knowledge of media production, streaming, and broadcasting. CX Codex +1 182installs microservices-expert microservices-expert — a skill for microservices architecture, service communication, and distributed workflows. Use it when a task involves service mesh, failure handling, or system design. CX Codex +1 181installs api-design-expert api-design-expert walks your agent through HTTP API design: REST resources, GraphQL against gRPC, versioning schemes, one error shape. Handy before the first endpoint gets written. CX Codex +1 180installs azure-expert azure-expert is a Claude Code skill for Microsoft Azure architecture, Azure Functions code, Cosmos DB queries, and Azure CLI commands. CX Codex +1 180installs

Project sponsors

Companies that keep this analytics open