API DESIGN / GitHub community
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.
“Review Protocol Buffer (.proto) and gRPC API changes for wire and JSON compatibility, safe schema evolution, rollout hazards, and RPC contract quality. Use when reviewing proto diffs, adding or changing messages and services, planning migrations, or diagnosing cross-version failures.”
01 / THE REASONING
Why this made the selection.
- Compatibility is evaluated on four independent dimensions (binary wire, named formats, generated source API, behavior and operations) instead of a single wire-compatibility verdict.
- Every non-trivial change is traced through mixed-version paths including rollback after new writers have emitted, with a verdict ladder that admits insufficient context.
02 / THE REVIEW RECORD
What we actually inspected.
Source review has boundaries.
A clear record is more useful than a “safe” badge.
Material inspected
- skills/protobuf-grpc-api-review/SKILL.md
- skills/protobuf-grpc-api-review/references/protobuf-compatibility.md
- LICENSE
- vercel-labs/skills@7407f3893ad4dceab546ac002c3ef806e4000c73:README.md
Our findings
- Default safety principles forbid field and enum number reuse, treat oneof moves and cardinality changes as breaking, and require idempotency before recommending retries.
- The false-positive guardrails refuse to demand streaming, retries or transcoding everywhere and refuse to flag additive optional fields as breaking.
- Findings carry a fixed evidence shape (severity, location, dimension, old-to-new change, failing scenario, remediation) plus a compatibility matrix and proving tests.
- The compatibility scenarios include an old reader modifying and reserializing a new message, and rollback after new writers emit values; retry recommendations require idempotency or deduplication for state-changing RPCs.
Not established by this review
- No .proto change was reviewed with this skill.
- Descriptor compilation and breaking-change checks were not executed.
- 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.
DOCUMENTED COMMAND
npx skills add github/awesome-copilot/skills/protobuf-grpc-api-review --skill protobuf-grpc-api-reviewRun 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/github/awesome-copilot/tree/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/skills/protobuf-grpc-api-review --skill protobuf-grpc-api-review- Install the complete skill directory with its references; select your AI tools and project or global scope.
- Review the instructions before invoking them. The source revision shown here is the one reviewed; the installer was not executed or version-pinned by this review.
Before you start
- Node.js/npm and git for the documented Skills installer
- An agent host that supports the skill format
- Access to old and new schema definitions plus deployment and consumer context
04 / FOLLOW THE EVIDENCE
The source trail.
Our notes are separate from the original resource.
Check upstream before adopting a new version.
https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/skills/protobuf-grpc-api-review/SKILL.md
Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, compatibility, access
https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/skills/protobuf-grpc-api-review/references/protobuf-compatibility.md
Supports: review, whySelected
https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/LICENSE
Supports: license
https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/README.md
Supports: install, compatibility, access
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md
Supports: install
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/git.ts
Supports: install
https://raw.githubusercontent.com/github/awesome-copilot/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/skills/protobuf-grpc-api-review/SKILL.md
Supports: review.findings, bestFor