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?

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

For streaming patterns: See grpc-patterns.md

Naming Conventions

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:

Related Skills (Cross-Plugin)

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