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
- Add protovalidate constraints to every field—this is not optional for production APIs
- For service templates, see assets/
3. Verify Changes
Always run after making changes:
buf format -w && buf lint
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 |
| Schema evolution, breaking changes |
best_practices.md |
| Validation constraints |
protovalidate.md |
| Complete service examples |
examples.md, assets/ |
| buf CLI, buf.yaml, buf.gen.yaml |
buf_toolchain.md |
| Migrating from protoc |
migration.md |
| Lint errors, common issues |
troubleshooting.md |
| Proto API review checklist |
review_checklist.md |
Project Setup
New Project
Create directory structure:
├── buf.yaml
├── buf.gen.yaml
└── proto/
└── company/
└── domain/
└── v1/
└── service.proto
buf.yaml sits above proto/: modules[].path resolves relative to the
config's own directory, so a buf.yaml inside proto/ makes Buf look for
proto/proto.
Use assets/buf.yaml as starting point
Add buf.build/bufbuild/protovalidate as a dependency in buf.yaml and run buf dep update
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
- Use next sequential field number
- Add protovalidate constraints: every field should have validation appropriate to its type (format validators, length bounds, numeric ranges, enum constraints, etc.)
- Document the field
- Run
buf format -w && buf lint
Remove a field
- Reserve the field number AND name:
reserved 4;
reserved "old_field_name";
- 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 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:
1---2name: protobuf3description: >-4 Use when working with Protocol Buffer (.proto) files, buf.yaml, buf.gen.yaml,5 or buf.lock. Covers proto design, buf CLI, gRPC/Connect services, protovalidate6 constraints, schema evolution, and troubleshooting lint/breaking errors.7filePatterns:8 - "**/*.proto"9 - "**/buf.yaml"10 - "**/buf.*.yaml"11 - "**/buf.gen.yaml"12 - "**/buf.gen.*.yaml"13 - "**/buf.lock"14metadata:15 source: https://skillmd.com/skills/stanfish06/protobuf16---1718# Protocol Buffers1920## When You Need This Skill2122- Creating or editing `.proto` files23- Setting up `buf.yaml` or `buf.gen.yaml`24- Designing gRPC or Connect services25- Adding protovalidate constraints26- Troubleshooting buf lint or breaking change errors2728## Core Workflow2930### 1. Match Project Style3132Before writing proto code, review existing `.proto` files in the project.33Match conventions for naming, field ordering, structural patterns, validation, and documentation style.34If none exists, ask the user what style should be used or an existing library to emulate.3536### 2. Write Proto Code3738- Apply universal best practices from [best_practices.md](references/best_practices.md)39- Add [protovalidate](references/protovalidate.md) constraints to every field—this is not optional for production APIs40- For service templates, see [assets/](assets/)4142### 3. Verify Changes4344**Always run after making changes:**4546```bash47buf format -w && buf lint48```4950Check for a Makefile first—many projects use `make lint` or `make format`.5152Fix all errors before considering the change complete.5354## Quick Reference5556| Task | Reference |57|------|-----------|58| Field types, enums, oneofs, maps | [quick_reference.md](references/quick_reference.md) |59| Schema evolution, breaking changes | [best_practices.md](references/best_practices.md) |60| Validation constraints | [protovalidate.md](references/protovalidate.md) |61| Complete service examples | [examples.md](references/examples.md), [assets/](assets/) |62| buf CLI, buf.yaml, buf.gen.yaml | [buf_toolchain.md](references/buf_toolchain.md) |63| Migrating from protoc | [migration.md](references/migration.md) |64| Lint errors, common issues | [troubleshooting.md](references/troubleshooting.md) |65| Proto API review checklist | [review_checklist.md](references/review_checklist.md) |6667## Project Setup6869### New Project70711. Create directory structure:72 ```73 ├── buf.yaml74 ├── buf.gen.yaml75 └── proto/76 └── company/77 └── domain/78 └── v1/79 └── service.proto80 ```8182 `buf.yaml` sits above `proto/`: `modules[].path` resolves relative to the83 config's own directory, so a `buf.yaml` inside `proto/` makes Buf look for84 `proto/proto`.85862. Use `assets/buf.yaml` as starting point873. Add `buf.build/bufbuild/protovalidate` as a dependency in `buf.yaml` and run `buf dep update`884. Use `assets/buf.gen.*.yaml` for code generation config8990### Code Generation Templates9192| Template | Use For |93|----------|---------|94| `buf.gen.go.yaml` | Go with gRPC |95| `buf.gen.go-connect.yaml` | Go with Connect |96| `buf.gen.ts.yaml` | TypeScript with Connect |97| `buf.gen.python.yaml` | Python with gRPC |98| `buf.gen.java.yaml` | Java with gRPC |99100### Proto File Templates101102Located in `assets/proto/example/v1/`:103104| Template | Description |105|----------|-------------|106| `book.proto` | Entity message, BookRef oneof, enum |107| `book_service.proto` | Full CRUD with batch ops, pagination, ordering |108109## Common Tasks110111### Add a new field1121131. Use next sequential field number1142. Add [protovalidate](references/protovalidate.md) constraints: every field should have validation appropriate to its type (format validators, length bounds, numeric ranges, enum constraints, etc.)1153. Document the field1164. Run `buf format -w && buf lint`117118### Remove a field1191201. Reserve the field number AND name:121 ```protobuf122 reserved 4;123 reserved "old_field_name";124 ```1252. Run `buf breaking --against '.git#branch=main'` to verify126127### Add protovalidate constraints128129Every field in a production API should have appropriate validation.130See [protovalidate.md](references/protovalidate.md) for the full reference.131132Common constraints:133- String formats: `.string.uuid`, `.string.email`, `.string.uri`, `.string.pattern`134- String bounds: `.string.min_len`, `.string.max_len`135- Numeric bounds: `.int32.gte`, `.uint32.lte`136- Enum validation: `.enum.defined_only`, `.enum.not_in = 0`137- Repeated bounds: `.repeated.min_items`, `.repeated.max_items`138- Required fields: `(buf.validate.field).required = true`139- Oneof required: `(buf.validate.oneof).required = true`140141## Verification Checklist142143After making changes:144- [ ] Every field has appropriate protovalidate constraints145- [ ] `buf format -w` (apply formatting)146- [ ] `buf lint` (check style rules)147- [ ] `buf breaking --against '.git#branch=main'` (if modifying existing schemas)