Skip to content
Skills Library
Programming · Building & coding

protobuf-dev

/protobuf-dev

Expert knowledge for Protocol Buffer development. Includes style guidelines, backward compatibility, design patterns, and build system detection (buf, Bazel). Use when creating, modifying, or reviewing .proto files or proto build rules.

Licence
MIT
Last repository change
24.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Expert knowledge for Protocol Buffer development. Includes style guidelines, backward compatibility, design patterns, and build system detection (buf, Bazel). Use when creating, modifying, or reviewing .proto files or proto build rules.

Original author description

Expert knowledge for Protocol Buffer development. Includes style guidelines, backward compatibility, design patterns, and build system detection (buf, Bazel). Use when creating, modifying, or reviewing .proto files or proto build rules.

How it works

  1. 1. Build System Detection
  2. 2. Proto File Style
  3. 3. Documentation: The Fine-Print Contract
  4. 4. Backward Compatibility
  5. 5. Design Patterns
  6. 6. Linting
  7. 7. Formatting
  8. 8. JSON Serialization Gotchas
Original SKILL.md headings · 446 lines, 1,765 words
SKILL.md preview
---
name: protobuf-dev
description: Expert knowledge for Protocol Buffer development. Includes style guidelines, backward compatibility, design patterns, and build system detection (buf, Bazel). Use when creating, modifying, or reviewing .proto files or proto build rules.
---

# Protocol Buffer Development Skill

Use this skill when the user **creates, modifies, or reviews `.proto` files or proto build rules**.

## 1. Build System Detection

Detect the project's build system and use the appropriate commands. **Do not assume one build system over another.**

### buf (default)

Use when a `buf.yaml` or `buf.gen.yaml` is present:

```bash
buf lint
buf format -w
buf generate          # generate code from protos
buf breaking --against '.git#branch=main'
```

### Bazel Projects

Use when `BUILD`, `BUILD.bazel`, or `WORKSPACE` files are present:

```python
load("@rules_proto//proto:defs.bzl", "proto_library")

proto_library(
    name = "example_proto",
    srcs = ["example.proto"],
)
```

Multi-language targets follow this pattern:

```python
load("@rules_proto//proto:defs.bzl", "proto_library")
load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library")
load("@rules_cc//cc:defs.bzl", "cc_proto_library")

proto_library(
    name = "example_proto",
    srcs = ["example.proto"],
)

cc_proto_library(
    name = "example_cc_proto",
    deps = [":example_proto"],
)

go_proto_library(
    name = "example_go_proto",
    importpath = "example.com/path/to/example_proto",
    protos = [":example_proto"],
)
```

## 2. Proto File Style

### Required File Structure

```protobuf
edition = "2024";

package mycompany.myservice.v1;

// Language-specific options
option go_package = "example.com/path/to/package/name_proto";
option java_package = "com.example.myservice.v1";

// Imports (sorted alphabetically)
import "google/protobuf/timestamp.proto";

// Messages and enums (alphabetically ordered)
```

### Naming Conventions

| Element        | Style                  | Example            |
|----------------|------------------------|--------------------|
| Message names  | PascalCase             | `UserProfile`      |
| Field names    | snake_case             | `user_name`        |
| Enum names     | PascalCase             | `StatusCode`       |
| Enum values    | SCREAMING_SNAKE_CASE   | `STATUS_ACTIVE`    |
| Enum zero value| Must end with `_UNKNOWN` or `_UNSPECIFIED` | `STATUS_UNKNOWN = 0` |
| Service names  | PascalCase             | `UserService`      |
| RPC names      | PascalCase             | `GetUser`          |

## 3. Documentation: The Fine-Print Contract

**Write protobuf comments like detailed fine-print contracts.** Proto files are high-level interfaces shared across services and across time. Anyone writing code that uses this interface should have a crystal-clear understanding of the expected values.

**Base rule:** When other developers read your code just by looking at the field name and type, they should know exactly what values to expect. If not, use a better name or add more comments/examples.

### Document Everything

All of these **MUST** have documentation comments:
- Messages
- Fields
- Enums
- Enum values
- Services and RPCs

### Include Example Values

Always show example values when the format isn't obvious:

```protobuf
// Bad - unclear format
string timestamp = 1;
string software_version = 2;

// Good - with examples
// Represents process error codes as a 3-character string.
// E.g. "001", "022"
string error_code = 1;

// The unique device identifier. E.g. "device-abc123"
string device_id = 2;

// Software version in release format. E.g. "22.01", "release-22.01"
string software_version = 3;
```

### Specify Zero or Missing Value Behavior

By default, unset scalar fields are indistinguishable from zero values (implicit field presence). **Document what empty/zero means:**

```protobuf
// The user's preferred language code (ISO 639-1).
// E.g. "en", "ko". Empty string means the system default will be used.
string language_code = 1;

// Maximum retry attempts. Zero means no retries (fail immediately).
int32 max_retries = 2;

// Optional deadline for the operation.
// If not set (null), the operation has no timeout.
google.protobuf.Timestamp deadline = 3;
```

### RPC Error Documentation

For RPC services, **document possible error codes and failure conditions:**

```protobuf
service DeviceService {
  // GetStatus returns the current device status.
  //
  // Errors:
  //   - NOT_FOUND: Device with the given ID does not exist.
  //   - UNAVAILABLE: Device is offline or unreachable.
  //   - PERMISSION_DENIED: Caller lacks permission to access this device.
  rpc GetStatus(GetStatusRequest) returns (GetStatusResponse);

  // ExecuteCommand sends a command to the device.
  //
  // Errors:
  //   - INVALID_ARGUMENT: Command parameters are malformed.
  //   - FAILED_PRECONDITION: Device is not in a state to execute command
  //     (e.g., emergency stop is active).
  //   - DEADLINE_EXCEEDED: Device did not respond within timeout.
  rpc ExecuteCommand(ExecuteCommandRequest) returns (ExecuteCommandResponse);
}
```

### Complete Example

```protobuf
// UserProfile represents a user's public profile information.
message UserProfile {
  // The unique identifier for the user. E.g. "user-abc123"
  // Empty string is invalid and should never occur.
  string user_id = 1;

  // User's display name. E.g. "John Doe"
  // Empty string means the user has not set a display name.
  string display_name = 2;

  // Status indicates the user's current account status.
  enum Status {
    // STATUS_UNKNOWN is the default unset value.
    // Treat as an error if received.
    STATUS_UNKNOWN = 0;
    // STATUS_ACTIVE indicates the user is active and can use the system.
    STATUS_ACTIVE = 1;
    // STATUS_SUSPENDED indicates the user is temporarily suspended.
    STATUS_SUSPENDED = 2;
  }

  // Current account status. STATUS_UNKNOWN should never be set explicitly.
  Status status = 3;
}
```

## 4. Backward Compatibility

### Never Change Field Numbers

Field numbers are part of the wire format. Changing them breaks all existing serialized data and communicating peers.

If you delete a field, **reserve** both the field number and name:

```protobuf
message UserProfile {
  reserved 3, 7;
  reserved "old_field", "legacy_name";
  // ...
}
```

Do not reorganize or renumber fields. Field numbers are not meant to be sequential or tidy.

### Never Change Package or Message Names

The protobuf package path is orthogonal to language-specific import paths (e.g., `go_package`, `java_package`). Changing the protobuf package or message name is risky because:

- `google.protobuf.Any` encodes the full type URL (e.g., `type.googleapis.com/mypackage.MyMessage`). If sender and receiver use different proto versions, unmarshaling fails.
- Adding a `package` line where none existed is equally risky.

```protobuf
edition = "2024";
package mycompany.myservice.v1;  // Changing this breaks Any compatibility
```

### Field Name Changes

Field names are backward compatible for the **binary** wire format. However, they can break:
- JSON serialization (field names are used as JSON keys)
- Text proto format
- Field masks

Treat field name changes with caution in APIs that use JSON or text proto.

### Deprecation Protocol

When deprecating a field:

1. Mark it with `[deprecated = true]` and add a comment explaining:
   - **Why** it is deprecated
   - **What replaces it** (the recommended alternative)
   - **When** it will be removed (if known)
2. Ensure it **still works** — deprecation does not mean removal
3. No new code should depend on it

```protobuf
// DEPRECATED: Use display_name instead. Will be removed in v2.
// The user's full name.
string full_name = 3 [deprecated = true];
```

When ready to remove, delete the field and reserve both the number and name.

## 5. Design Patterns

### Prefer Enums Over Booleans

Boolean fields often grow beyond two states, and they have backward compatibility problems.

**The expansion problem:**

```protobuf
// Bad - what if we add bzip, zstd later?
bool compressed = 2;

// Good - extensible
enum Compression {
  COMPRESSION_UNSPECIFIED = 0;
  COMPRESSION_NONE = 1;
  COMPRESSION_GZIP = 2;
  COMPRESSION_ZSTD = 3;
}
Compression compression = 2;
```

**The backward compatibility problem:**

```protobuf
// Bad - old servers won't set this field, so the zero value (false)
// is indistinguishable from an explicit "not successful"
bool success = 2;

// Good - old servers return UNSPECIFIED, which clients can handle
enum Result {
  RESULT_UNSPECIFIED = 0;
  RESULT_SUCCESS = 1;
  RESULT_FAILURE = 2;
}
Result result = 2;
```

Code handling an enum can detect unknown values and fail explicitly, rather than silently misinterpreting a default `false`.

### Prefer Nested Over Flattened Messages

Group related fields into sub-messages for clarity and reusability:

```protobuf
// Good - nested structure
message MachineMetrics {
  // Primary key identifying which device these metrics belong to.
  string device_id = 1;

  // Process represents a single OS process on the device.
  message Process {
    // The process ID. E.g. 12345
    int32 pid = 1;
    // Effective user name of the process owner. E.g. "appuser"
    string user = 2;
    // CPU usage percentage (2 decimal points). E.g. 99.99
    float cpu_used_percentage = 3;
  }

  // Running processes on the device.
  repeated Process processes = 2;
}
```

### Use Well Known Types

Prefer Well Known Types over hand-rolled equivalents.

#### Timestamp

Use `google.protobuf.Timestamp` instead of strings for time points:

```protobuf
// Bad - ambiguous format, no type safety
string timestamp = 1;

// Good - standard type with language-specific utility functions
google.protobuf.Timestamp created_at = 1;
```

`Timestamp` serializes to RFC 3339 in JSON (e.g., `"2024-01-15T07:34:51.119Z"`) and to an efficient binary format on the wire. All supported languages provide utility functions for conversion.

If you must use a string for a timestamp, use RFC 3339 or ISO 8601 and document the format explicitly.

#### Duration

Use `google.protobuf.Duration` for time spans:

```protobuf
// Bad
int64 timeout_ms = 1;

// Good
google.protobuf.Duration timeout = 1;
```

#### Any

Use `google.protobuf.Any` for polymorphic message fields. Be aware that `Any` encodes the full type URL, so all possible message types must be available in the type registry at deserialization time.

```protobuf
import "google/protobuf/any.proto";

message Event {
  google.protobuf.Timestamp time = 1;
  // The event payload. All possible event types must be registered.
  google.protobuf.Any payload = 2;
}
```

#### Other Useful WKTs

| Type | Use For |
|------|---------|
| `google.protobuf.Struct` | Arbitrary JSON-like data |
| `google.protobuf.FieldMask` | Partial updates |
| `google.protobuf.Empty` | RPCs with no request/response payload |
| `google.protobuf.StringValue` (wrappers) | Distinguishing "unset" from zero with implicit presence |

## 6. Linting

### buf lint (recommended)

```bash
buf lint
```

Configure rules in `buf.yaml`:

```yaml
version: v2
lint:
  use:
    - STANDARD
    - COMMENTS
```

The `COMMENTS` rule set enforces documentation on messages, fields, enums, enum values, services, and RPCs.

### Bazel Integration

Projects using Bazel may have custom lint test rules. Check the project's build rules for proto lint targets and follow the existing pattern:

```python
# Example pattern - actual rule names vary by project
proto_library(
    name = "example_proto",
    srcs = ["example.proto"],
)

# Check project's build_rules/ or tools/ for the actual lint rule
proto_lint_test(
    name = "example_proto_lint",
    protos = [":example_proto"],
)
```

**Naming convention:** `{name}_proto` for the library, `{name}_proto_lint` for the lint test.

## 7. Formatting

### buf format

```bash
buf format -w          # Write changes
buf format -d          # Diff (dry run)
```

### clang-format

Some projects use `clang-format` for proto files:

```bash
clang-format -i *.proto
```

### Bazel

Check if the project has a format target:

```bash
bazel run //:format    # Project-specific target name
```

## 8. JSON Serialization Gotchas

When serializing proto messages to JSON, be aware of these common pitfalls:

- **Default value stripping:** By default, fields with zero/default values are omitted from JSON output. Use your language's "include default values" option if you need them.
- **Field name casing:** Proto JSON uses camelCase by default (e.g., `user_name` becomes `userName`). Use the "preserve proto field names" option if downstream systems expect snake_case.
- **Any type registry:** When using `google.protobuf.Any` with JSON, all possible message types must be available in the type registry, or deserialization will fail.

Versions

The database has no other skills named protobuf-dev.

Database snapshot: 13.11.2026 · package version ac467ad0753e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100protobuf
    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.
  • 100rails-protobuf
    This skill should be used when building, extending, or reviewing a Rails app whose API schema is Protocol Buffers, served with connect_rpc_rails (Connect RPC as controller actions) and protobufable (protobuf request bodies, responses, columns, errors). Use it when adding an RPC,…
  • 100buf-cli-lint-breaking-build
    Use for any question or task about the buf CLI, including adding buf to a CI workflow and reading a buf breaking or buf lint error: buf build, buf lint (STANDARD rules), buf breaking against a git or BSR baseline, buf format, and which rule category fits each consumer. Explains…
  • 100protobuf
    Define data schemas with Protocol Buffers (protobuf), Google's language-neutral binary serialization format, and generate typed code for TypeScript, Go, Python and other languages. Use when the user asks about ".proto files", "protobuf schema", "gRPC service definition", "buf…
  • 100go-dev
    Expert knowledge for Go development. Includes idiomatic patterns, error handling, testing, package naming, and build system detection (go toolchain, Bazel, Makefile). Use when writing, testing, or building Go code.
  • 100protobuf-compat-checking
    Wraps `buf breaking` to compare a Protobuf schema against a past version, classifies breaking changes by category (FILE / PACKAGE / WIRE_JSON / WIRE), configures buf.yaml rule selection plus per-path exemptions, and gates CI on the exit code. Use when reviewing `.proto` changes…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.