Index of every page on this site: llms.txt
All skills
github avatar

/protobuf-grpc-api-review

@f10fdb8 official
by githubgithub/awesome-copilot41k stars
5,399
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/github/awesome-copilot/protobuf-grpc-api-review

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈78 tokens for metadata: the name and description. ≈1.6k when used: this file. ≈3.1k more on demand in 2 files.

Description uses 3.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈311 characters, or 3.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Protobuf and gRPC API Review

Review .proto and related gRPC changes as long-lived contracts. Distinguish what the wire format permits from what generated clients, JSON users, stored data, and mixed-version deployments can safely tolerate.

Start With the Compatibility Envelope

Before deciding whether a change is safe, determine:

  • the old and new schema, not only the final file
  • whether payloads use binary protobuf, ProtoJSON, text format, or more than one encoding
  • whether messages persist in databases, queues, logs, caches, or events
  • whether clients exist outside the repository or release independently
  • the protobuf syntax or edition and the generated languages/runtime versions
  • whether HTTP/JSON transcoding, reflection, service config, or schema registries expose the contract
  • the deployment order, rollback window, and duration of mixed-version operation

If context is missing, state the assumption and lower confidence. Do not call a change backward-compatible from the new schema alone.

Review Workflow

1. Inventory Contract Changes

Compare the old and new definitions by fully qualified symbol. Record:

  • message fields: number, name, type, cardinality, presence, oneof, defaults, and relevant options
  • enums: value name, number, aliases, reservations, and zero value
  • services: package, service, method, request and response types, and streaming mode
  • generated API inputs: package options, outer class names, namespaces, and custom options

Ignore formatting-only changes after confirming they do not alter descriptors or generated APIs.

2. Evaluate Four Compatibility Dimensions

Assess each affected symbol independently:

  1. Binary wire — can old and new readers parse both old and new bytes without corruption or loss?
  2. Named formats — do ProtoJSON, text-format, REST-transcoded, or name-based consumers still work?
  3. Source and generated API — will regenerated clients compile and preserve presence, enum, and accessor behavior?
  4. Behavior and operations — do status codes, retry safety, deadlines, authorization, streaming, and resource bounds preserve the RPC contract?

Read protobuf compatibility rules for field, enum, presence, oneof, and serialization changes. Read gRPC contract review when services, methods, or runtime behavior change.

3. Trace Mixed-Version Scenarios

For every non-trivial change, reason through these paths:

  • old writer -> new reader
  • new writer -> old reader
  • old reader modifies and reserializes a new message
  • rollback after new writers have emitted new values
  • persisted old data read after the migration

For conditionally compatible changes, identify the exact writer constraint and the point at which it may be relaxed. A safe rollout commonly requires deploying readers before writers and retaining the old field or method until rollback is no longer needed.

4. Review Repository Evidence

Use the repository's own tooling when available:

  • compile descriptors with the project's protoc, Buf, Gradle, Maven, Bazel, or language-specific task
  • run configured breaking-change or lint checks
  • inspect generated-code diffs only when they are committed by repository convention
  • search call sites for exhaustive enum switches, presence assumptions, JSON field names, method paths, status handling, and retry configuration
  • look for compatibility fixtures or descriptor baselines before proposing a new mechanism

Do not claim a check passed unless you ran it. If a required tool or baseline is unavailable, name the unverified risk.

5. Produce an Actionable Review

Lead with one verdict:

  • Compatible — safe within the stated compatibility envelope
  • Rollout-dependent — parseable, but safe only with explicit sequencing or value constraints
  • Breaking — causes wire, named-format, source, or behavioral incompatibility
  • Insufficient context — the old schema, encoding, consumers, or deployment model is unknown

Then provide only evidence-backed findings. For each finding include:

[severity] Short title
Location: file and symbol or changed lines
Dimension: binary | JSON/text | source | behavior/operations
Change: old contract -> new contract
Impact: concrete failing mixed-version scenario
Remediation: smallest safe schema change or staged migration

Use blocker for corruption, unparsable data, tag reuse, or an unavoidable production break; high for likely cross-version data loss or unsafe RPC behavior; medium for bounded compatibility or operability risks; and low for maintainability issues that do not break the contract. Do not inflate style preferences into compatibility findings.

Conclude with:

  • a compact compatibility matrix for changed symbols
  • the rollout/rollback sequence if migration is required
  • targeted tests that would prove the remaining assumptions

Default Safety Principles

  • Never reuse a field or enum number, even after deletion; reserve deleted numbers and usually names.
  • Treat field-number changes and moving fields into an existing oneof as breaking.
  • Treat type and cardinality changes as migrations, even when their binary wire types are compatible.
  • Remember that adding a field or enum value can still break generated code or exhaustive consumers.
  • Review ProtoJSON separately: names and unknown-field behavior make its compatibility envelope narrower than binary protobuf.
  • Preserve unknown fields through read-modify-write paths when forward compatibility depends on them.
  • Prefer additive evolution: add a new field or RPC, migrate readers and writers, deprecate the old contract, then remove it only after the compatibility window closes.
  • Never recommend retries for a state-changing RPC without establishing idempotency or a deduplication mechanism.
  • Require realistic client deadlines and cancellation-aware server work for production RPCs.

Avoid False Positives

  • Do not require every service to use streaming, retries, health checks, or HTTP transcoding.
  • Do not flag a new optional field as breaking solely because old clients ignore it.
  • Do not call a wire-compatible type change safe without checking value ranges and rollout order.
  • Do not assume a renamed field is harmless when JSON, text format, reflection, or generated source APIs are consumers.
  • Do not demand reservations for fields that never shipped; ask for release history when that distinction matters.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts20d3 checks · Risk SAFE
  • Gen Agent Trust Hub20d

    This skill provides a set of guidelines and reference materials for reviewing Protocol Buffer and gRPC API changes. It focuses on ensuring backward compatibility, wire safety, and adherence to gRPC contract best practices. No malicious code, exfiltration patterns, or unauthorized access attempts were detected.

  • Socket20d

    No alerts

  • Snyk20d

    Risk: LOW · No issues

Signed by skilld at f10fdb8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago

README badge

README badge for github/awesome-copilot/protobuf-grpc-api-review