melodic-software/protobuf-design

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:

1. Invoke docs-management skill for API contract patterns
2. Verify proto3 syntax via MCP servers (context7 for latest spec)
3. 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

1. Identify Resources: What entities does the service manage?
2. Define Messages: Data structures for each resource
3. Design Service Methods: CRUD operations, queries, commands
4. Add Streaming: Where real-time updates needed
5. Document: Comments for all messages and fields
6. Lint: Use Buf or protolint for consistency
7. Version: Plan for schema evolution
8. 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