From formal-specification
Designs proto3 Protocol Buffers schemas for gRPC services: messages, enums, RPC patterns, streaming, naming conventions, C# ASP.NET Core implementation.
npx claudepluginhub melodic-software/claude-code-plugins --plugin formal-specificationThis skill is limited to using the following tools:
Use this skill when:
Generates gRPC service definitions, stubs, and implementations from Protocol Buffers. Supports streaming RPCs, interceptors, health checks, TLS, tests, and REST gateways for high-performance APIs.
Generates OpenAPI 3.1, AsyncAPI 3.0, or Protocol Buffers contracts from natural language API requirements for contract-first development.
Designs and edits .proto files, configures buf.yaml/gen.yaml/lock, builds gRPC/Connect services, adds protovalidate constraints, handles schema evolution, and troubleshoots buf lint/breaking errors.
Share bugs, ideas, or general feedback.
Use this skill when:
Before creating protobuf definitions:
docs-management skill for API contract patterns| 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 |
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
| 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
| 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 |
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 |
| 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-authoringskill may be added if demand warrants.
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)
Last Updated: 2026-01-17