Name: protobuf
Author: bufbuild

Use when working with Protocol Buffer (.proto) files, buf.yaml, buf.gen.yaml, or buf.lock. Covers proto design, buf CLI, gRPC/Connect services, protovalidate constraints, schema evolution, and troubleshooting lint/breaking errors.

Protocol Buffers When You Need This Skill Creating or editing .proto files Setting up buf.yaml or buf.gen.yaml Designing gRPC or Connect services Adding protovalidate constraints Troubleshooting buf lint or breaking change errors Core Workflow 1. Match Project Style Before writing proto code, review existing .proto files in the project. Match conventions for naming, field ordering, structural patterns, validation, and documentation style. If none exists, ask the user what style should be used or an existing library to emulate. 2. Write Proto Code Apply universal best practices from [best practices.md](references/best practices.md) Add [protovalidate](references/protovalidate.md) constraints to every field—this is not optional for production APIs For service templates, see [assets/](assets/) 3. Verify Changes Always run after making changes: Check for a Makefile first—many projects use make lint or make format . Fix all errors before considering the change complete. Quick Reference Task Reference Field types, enums, oneofs, maps [quick reference.md](references/quick reference.md) Schema evolution, breaking changes [best practices.md](references/best practices.md) Validation constraints [protovalidate.md](references/protovalidate.md) Complete service examples [examples.md](references/examples.md), [assets/](assets/) buf CLI, buf.yaml, buf.gen.yaml [buf toolchain.md](references/buf toolchain.md) Migrating from protoc [migration.md](references/migration.md) Lint errors, common issues [troubleshooting.md](references/troubleshooting.md) Proto API review checklist [review checklist.md](references/review checklist.md) Project Setup New Project 1. Create directory structure: 2. Use assets/buf.yaml as starting point 3. Add buf.build/bufbuild/protovalidate as a dependency in buf.yaml and run buf dep update 4. Use assets/buf.gen. .yaml for code generation config Code Generation Templates Template Use For buf.gen.go.yaml Go with gRPC buf.gen.go connect.yaml Go with Connect buf.gen.ts.yaml TypeScript with Connect buf.gen.python.yaml Python with gRPC buf.gen.java.yaml Java with gRPC Proto File Templates Located in assets/proto/example/v1/ : Template Description book.proto Entity message, BookRef oneof, enum book service.proto Full CRUD with batch ops, pagination, ordering Common Tasks Add a new field 1. Use next sequential field number 2. Add [protovalidate](references/protovalidate.md) constraints: every field should have validation appropriate to its type (format validators, length bounds, numeric ranges, enum constraints, etc.) 3. Document the field 4. Run buf format w && buf lint Remove a field 1. Reserve the field number AND name: 2. Run buf breaking against '.git branch=main' to verify Add protovalidate constraints Every field in a production API should have appropriate validation. See [protovalidate.md](references/protovalidate.md) for the full reference. Common constraints: String formats: .string.uuid , .string.email , .string.uri , .string.pattern String bounds: .string.min len , .string.max len Numeric bounds: .int32.gte , .uint32.lte Enum validation: .enum.defined only , .enum.not in = 0 Repeated bounds: .repeated.min items , .repeated.max items Required fields: (buf.validate.field).required = true Oneof required: (buf.validate.oneof).required = true Verification Checklist After making changes: [ ] Every field has appropriate protovalidate constraints [ ] buf format w (apply formatting) [ ] buf lint (check style rules) [ ] buf breaking against '.git branch=main' (if modifying existing schemas)