Protocol Buffers Design Skill

When to Use This Skill

Use this skill when:

• Designing gRPC services - Protocol Buffers (proto3) for typed service contracts

• Schema definition - Messages, enums, services, streaming patterns

• Implementing in C# - gRPC with ASP.NET Core

• Schema evolution - Backward/forward compatibility, versioning

MANDATORY: Documentation-First Approach

Before creating protobuf definitions:

• Invoke docs-management skill for API contract patterns

• Verify proto3 syntax via MCP servers (context7 for latest spec)

• Base all guidance on Google's Protocol Buffers documentation

Why Protocol Buffers?

Benefit Description

Efficient Binary format, 3-10x smaller than JSON

Typed Strong typing with code generation

Versioned Built-in backward/forward compatibility

Cross-Language Supports C#, Java, Python, Go, etc.

gRPC Integration Native service definition for gRPC

Proto3 Structure Overview

syntax = "proto3";

package ecommerce.orders.v1;

option csharp_namespace = "ECommerce.Orders.V1";

import "google/protobuf/timestamp.proto";

service OrderService { rpc GetOrder(GetOrderRequest) returns (Order); rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse); rpc WatchStatus(WatchRequest) returns (stream StatusUpdate); }

enum OrderStatus { ORDER_STATUS_UNSPECIFIED = 0; ORDER_STATUS_DRAFT = 1; ORDER_STATUS_SUBMITTED = 2; }

message Order { string id = 1; string customer_id = 2; OrderStatus status = 3; google.protobuf.Timestamp created_at = 4; }

For complete template: See proto-syntax.md

Quick Reference

gRPC RPC Types

Pattern Syntax Use Case

Unary rpc Get(Req) returns (Resp)

Simple CRUD

Server Stream rpc List(Req) returns (stream Resp)

Large results, updates

Client Stream rpc Upload(stream Req) returns (Resp)

Batch uploads

Bidirectional rpc Chat(stream Req) returns (stream Resp)

Real-time sync

For streaming patterns: See grpc-patterns.md

Naming Conventions

Element Convention Example

Package lowercase.dots.version ecommerce.orders.v1

Service PascalCase + Service OrderService

RPC PascalCase verb CreateOrder

Message PascalCase OrderCreatedEvent

Field snake_case customer_id

Enum SCREAMING_PREFIX_VALUE ORDER_STATUS_DRAFT

Workflow

• Identify Resources: What entities does the service manage?

• Define Messages: Data structures for each resource

• Design Service Methods: CRUD operations, queries, commands

• Add Streaming: Where real-time updates needed

• Document: Comments for all messages and fields

• Lint: Use Buf or protolint for consistency

• Version: Plan for schema evolution

• Generate: Create client/server code

References

Load on-demand based on need:

Reference Load When

proto-syntax.md Creating proto definitions, well-known types, advanced patterns

grpc-patterns.md Designing streaming services (server, client, bidirectional)

csharp-implementation.md Implementing gRPC in .NET/C# with ASP.NET Core

schema-evolution.md Planning schema changes, Buf CLI, versioning

Related Skills (Cross-Plugin)

Phase Skill Plugin Purpose

DESIGN protobuf-design (this skill) formal-specification Architecture research, pattern selection

AUTHORING N/A spec-driven-development Gap: protobuf-authoring not yet created

Workflow: Design (research gRPC patterns) → Author (create .proto files) → Generate (code generation)

Note: Unlike OpenAPI and AsyncAPI, protobuf authoring is typically straightforward enough that the design skill's C# implementation reference covers concrete creation. A dedicated protobuf-authoring skill may be added if demand warrants.

External References

• Protocol Buffers Documentation - Official Google documentation

• gRPC Documentation - Official gRPC guides

• Buf CLI - Modern protobuf tooling

• Google API Design Guide - Resource-oriented API patterns

• gRPC for .NET - ASP.NET Core gRPC docs

MCP Research

For current protobuf patterns and tools:

perplexity: "Protocol Buffers proto3" "gRPC service design patterns" context7: "grpc" (for official documentation) microsoft-learn: "gRPC ASP.NET Core" (for .NET implementation)

Version History

• v2.0.0 (2026-01-17): Refactored to progressive disclosure pattern

• Extracted 4 reference files (~550 lines)

• Hub reduced from 700 to ~130 lines

• Updated NuGet package versions (Grpc.AspNetCore 2.71.0)

• v1.0.0 (2025-12-26): Initial release

Last Updated: 2026-01-17