--- title: "Buf Protocol Buffers Design and Toolchain: review, setup & limitations · Undominated.ai" canonical: https://undominated.ai/skills/buf-protobuf/ description: "Official Buf skill for Protocol Buffers (.proto) design, buf.yaml toolchain configuration, Connect/gRPC service authoring, and breaking change prevention." --- # Buf Protocol Buffers Design and Toolchain: review, setup & limitations · Undominated.ai > Official Buf skill for Protocol Buffers (.proto) design, buf.yaml toolchain configuration, Connect/gRPC service authoring, and breaking change prevention. [← Explore all skills](/skills/) DEVELOPER TOOLS / Buf Technologies # Buf Protocol Buffers Design and Toolchain Official Buf skill for Protocol Buffers (.proto) design, buf.yaml toolchain configuration, Connect/gRPC service authoring, and breaking change prevention. [See setup guidance ↓](#setup)[Original source ↗](https://github.com/bufbuild/claude-plugins) SOURCE REVIEW Reviewed 2026-10-15 Evidence 3 linked sources Publisher Buf Technologies Licence [Apache-2.0 ↗](https://github.com/bufbuild/claude-plugins/blob/c4766e5fff1b52283f38bd61122103efe58c60fd/LICENSE) Revision c4766e5fff1b [Read what was—and wasn’t—checked ↓](#review) “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.” [Buf Technologies · upstream description ↗](https://github.com/bufbuild/claude-plugins/blob/c4766e5fff1b52283f38bd61122103efe58c60fd/plugins/protobuf/skills/protobuf/SKILL.md) Our analysis follows below. 01 / THE REASONING ## Why this made the selection. - Protovalidate constraints are required on fields, not left as a later cleanup. - Removing a field reserves both the number and the name, then buf breaking checks the result. ### A good fit for - Editing .proto files in a repository that already has buf.yaml - Adding a field with the next number, a constraint, and a buf lint run - Review schema evolution together with application-side validation boundaries. ### Weigh up before choosing - The skill says not to invent a style when the repo has none; ask which style to copy. - Field removal must reserve the number and the name. - buf format and buf lint must pass before the change is considered done. - This review did not execute the skill. - Annotations do not enforce validation without compatible runtime integration; adding required constraints can reject previously valid messages even when wire-compatible. 02 / THE REVIEW RECORD ## What we actually inspected. Source review has boundaries. A clear record is more useful than a “safe” badge. ### Material inspected - plugins/protobuf/skills/protobuf/SKILL.md - plugins/protobuf/skills/protobuf/references/best_practices.md - README.md - LICENSE ### Our findings - The pinned skill matches existing proto style first, then applies references/best_practices.md and requires protovalidate constraints on every production field. - Verification prefers a Makefile lint or format target when one exists, otherwise buf format -w and buf lint. - New projects start from assets/buf.yaml, add the protovalidate dependency, and run buf dep update. - Codegen templates are split by stack, including buf.gen.go.yaml and buf.gen.go-connect.yaml. - The definition separates format/lint/breaking checks and supplies language-specific generation templates; the previously catalogued LICENSE-APACHE URL is absent, while pinned LICENSE contains Apache-2.0 terms. ### Not established by this review - The skill was not executed inside a host agent. - Not executed: it was not installed or run. The review applies to the material and revision named here. A newer upstream release can change its behavior. 03 / PUT IT TO WORK ## Add a skill to your workflow. [Upstream setup instructions ↗](https://github.com/bufbuild/claude-plugins/blob/c4766e5fff1b52283f38bd61122103efe58c60fd/plugins/protobuf/skills/protobuf/SKILL.md) DOCUMENTED COMMAND npx skills add bufbuild/claude-plugins/plugins/protobuf/skills/protobuf Copy command ↗ Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above. Optional: install the reviewed revision Keeps the original source and installer version where recorded, while leaving your AI tools and installation scope for you to choose. npx skills add https://github.com/bufbuild/claude-plugins/tree/c4766e5fff1b52283f38bd61122103efe58c60fd/plugins/protobuf/skills/protobuf Copy reviewed-revision command ↗ - The README install line is /plugin install protobuf@buf-plugins after adding the marketplace. - Install plugins/protobuf/skills/protobuf at revision c4766e5fff1b52283f38bd61122103efe58c60fd, including references and assets. - The buf CLI must be installed before format, lint, or breaking checks. - Match repository proto conventions, reserve removed names/numbers and compare against the true base schema with the project Buf checks. ### Before you start - buf CLI - A protobuf repository, or permission to create buf.yaml ### Compatibility Agent Skills hosts · Buf CLI v1.x+ · Protocol Buffers v3 / proto3 ### Implementation Markdown · Protobuf · YAML ### Protocol buffer and Buf toolchain best practices - Write .proto, buf.yaml, and buf.gen.yaml - Run buf format, buf lint, buf dep update, and buf breaking - Network access for buf dep update against buf.build - Edits proto and generation configuration; remote plugins/dependencies may be fetched during generation. ### Cost model Apache-2.0 licence; the BSR dependency fetch may need network access but no key is named for public modules. 04 / FOLLOW THE EVIDENCE ## The source trail. Our notes are separate from the original resource. Check upstream before adopting a new version. - [Buf Protocol Buffers skill definition ↗](https://github.com/bufbuild/claude-plugins/blob/c4766e5fff1b52283f38bd61122103efe58c60fd/plugins/protobuf/skills/protobuf/SKILL.md) Checked 2026-10-14 https://github.com/bufbuild/claude-plugins/blob/c4766e5fff1b52283f38bd61122103efe58c60fd/plugins/protobuf/skills/protobuf/SKILL.md Supports: summary, whySelected, bestFor, limitations - [Corrected pinned Apache-2.0 licence ↗](https://github.com/bufbuild/claude-plugins/blob/c4766e5fff1b52283f38bd61122103efe58c60fd/LICENSE) Checked 2026-10-14 https://github.com/bufbuild/claude-plugins/blob/c4766e5fff1b52283f38bd61122103efe58c60fd/LICENSE Supports: license - [2026-10-15 W33 source re-review at the existing pin ↗](https://raw.githubusercontent.com/bufbuild/claude-plugins/c4766e5fff1b52283f38bd61122103efe58c60fd/plugins/protobuf/skills/protobuf/SKILL.md) Checked 2026-10-15 https://raw.githubusercontent.com/bufbuild/claude-plugins/c4766e5fff1b52283f38bd61122103efe58c60fd/plugins/protobuf/skills/protobuf/SKILL.md Supports: upstreamDescription, review.notTested, review.reviewedAt KEEP COMPARING ## Other approaches to consider. Related by category or shared topics. These are alternatives to inspect, not a measured quality order. [### Sentry Claude Settings Audit ↗ Audits repository tooling to generate least-privilege Claude Code settings.json read-only allowlists.](/skills/getsentry-claude-settings-audit/)[### Protobuf gRPC API Review ↗ Reviews .proto and gRPC changes as long-lived contracts across binary wire, JSON and text formats, generated APIs and runtime behavior, with mixed-version rollout tracing and a four-rung verdict.](/skills/github-protobuf-grpc-api-review/)[### Ruff Recursive Fix ↗ Enforces Python code quality with scoped Ruff runs: safe fixes first, unsafe fixes second with diff review each pass, then targeted manual remediation under explicit stop criteria.](/skills/github-ruff-recursive-fix/) [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/) ## Continue your investigation - [Choose a toolkit](/tools/) - [Inspect execution hosts](/agents/) - [Check tool access](/mcp-servers/) - [Check project dependencies](/check-repo/)