protobuf_skill

Overview

This skill helps engineers design, edit, and validate Protocol Buffer schemas and Buf configuration files for production APIs. It covers .proto authoring, protovalidate constraints, buf CLI workflows, code generation templates, and troubleshooting lint or breaking-change errors. Use it to enforce consistent schema style, safe schema evolution, and reliable codegen across languages.

How this skill works

I inspect existing .proto files and Buf configs to match project conventions, then propose or modify proto definitions with required protovalidate constraints. I recommend and generate buf.yaml and buf.gen.yaml snippets for your target languages and toolchains, and I validate changes with the recommended Buf commands (format, lint, breaking). When issues appear, I diagnose lint and breaking errors and suggest minimal, safe fixes.

When to use it

• Creating or editing .proto files for gRPC or Connect services
• Adding protovalidate constraints to ensure production-safe inputs
• Setting up or updating buf.yaml, buf.gen.yaml, or buf.lock for code generation
• Verifying schema evolution and preventing breaking changes before merge
• Troubleshooting buf lint or buf breaking errors reported in CI

Best practices

• Match existing project style for naming, field ordering, and docs before adding new proto files
• Add protovalidate constraints to every field (format, bounds, required) for production APIs
• Use next sequential field numbers; reserve numbers/names when removing fields
• Always run buf format -w && buf lint after edits; use make lint/format if provided
• Run buf breaking --against '.git#branch=main' when modifying existing schemas

Example use cases

• Add a new optional email field with .string.email and max length validation to a User proto
• Create buf.gen.*.yaml config to generate Go gRPC and TypeScript Connect clients simultaneously
• Migrate a legacy protoc-based project to Buf with buf.yaml and dependency protovalidate
• Resolve a buf lint error by fixing a naming violation and applying buf format
• Verify a refactor won’t break clients by running buf breaking against main