skills.rest
reliant-labs
reliant-labsOFFICIAL
Explore all skills by this author →
WebsiteGitHub

proto-breaking

Enforce buf breaking checks in forge-generated GitHub PR workflows.

4|1|Updated Apr 12, 2026
Search Tags:#versioning#github actions#protobuf#backward compatibility#ci gating#buf breaking#deprecation flow
One-click install
npx skills add https://github.com/reliant-labs/forge --skill proto-breaking
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: proto-breaking
Source: https://github.com/reliant-labs/forge/tree/main/internal/templates/project/skills/forge/proto-breaking
Command: npx skills add https://github.com/reliant-labs/forge --skill proto-breaking

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Prevents accidental Protocol Buffer breaking changes from reaching downstream clients by standardizing how forge projects enforce compatibility and how teams evolve protos over time.

Core Features & Use Cases

  • CI breaking-change gate generation: Ensures a Tier-1 GitHub workflow runs buf breaking on PRs that modify proto/**, buf.yaml, or buf.gen.yaml, comparing against main.
  • Guided deprecation-to-removal workflow: Covers the 99% path—add the new shape, deprecate the old, migrate callers, then remove safely using reserved to satisfy buf breaking.
  • Rare hard-break handling: Describes the version-rev approach (e.g., v1 frozen, new v2 package) and when to use it.
  • Legitimate override mechanisms: Provides an auditable [skip-buf-breaking] PR commit marker, targeted buf.yaml ignore entries for single-file exceptions, and cautions against disabling the workflow.
  • Local verification matching CI: Shows how to run buf breaking locally against the same baseline as CI for confidence before merging.

Quick Start

Use the proto-breaking skill to generate and follow a deprecation and removal plan that makes buf breaking pass by verifying locally with the same --against baseline as your CI workflow.

Frequently Asked Questions about proto-breaking

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent breaking protobuf changes from reaching downstream clients in CI?▼

To prevent breaking protobuf changes, configure a GitHub PR workflow to run `buf breaking` against your `main` branch whenever a PR modifies `proto/**` or `buf.yaml` files.

What is the safest way to remove a field from a protobuf without breaking compatibility?▼

The safest way to remove a protobuf field is a deprecate-then-remove process: add the new shape, deprecate the old, migrate callers, and use `reserved` tags or names before final removal.

When should I use a version-rev hard break instead of a deprecation flow for protobufs?▼

Use a version-rev hard break for rare, incompatible proto changes by freezing the current package (e.g., `v1`) and creating a new package version (e.g., `v2`) for future updates.

Can I override or skip buf breaking checks for a specific GitHub PR?▼

Yes, you can override `buf breaking` checks using the auditable `[skip-buf-breaking]` commit marker or by adding targeted ignore entries in `buf.yaml` for single-file exceptions.

How do I verify protobuf backward compatibility locally before merging a PR?▼

Verify protobuf backward compatibility locally by running `buf breaking` with the same `--against` baseline reference that your CI workflow uses to ensure your checks match.

Which buf breaking rules should I use for JSON wire compatibility in protobufs?▼

For JSON wire compatibility in protobufs, choose appropriate breaking rules in `buf.yaml` such as `WIRE_JSON` to enforce the specific compatibility standards your clients require.

Related Skills

Explore More Software Engineering Skills→
way-platformway-platform
6

protobuf

Manage Protocol Buffers workflows with Buf linting, validation, and code generation.

Official
Advanced
meridianhubmeridianhub
10

skill-schema-evolution

Enforces safe protobuf schema evolution with buf breaking-change detection.

Official
Advanced
ArtisanCloudArtisanCloud
357

crud-proto-gen

Generate protobuf definitions and Go stubs for PowerX services.

Official
Intermediate
viqueenviqueen
1

review-proto

Audit Protocol Buffer files in pull requests against best-practice checklists.

Community
Intermediate