imrenagi/skills

Overview

This skill provides practical guidelines for writing, reviewing, and refactoring Protocol Buffer (proto3) schemas to ensure consistency, clarity, and safe API evolution. It codifies resource design, method patterns, field conventions, compatibility rules, and style recommendations drawn from established API best practices. Use it to reduce interoperability issues and avoid breaking changes when generating code or evolving services.

How this skill works

The skill inspects protobuf design choices and recommends patterns for resource names, message structure, RPC methods, field naming, and versioning. It highlights AIP-based conventions for resource annotations, HTTP transcoding, long-running operations, pagination, and field behaviors. It also flags common compatibility risks (renaming fields, changing tag numbers, altering enum zero values) and suggests mitigations like field deprecation, reserving tags, and using field masks.

When to use it

• Defining new gRPC services, message types, or resource schemas.
• Reviewing or refactoring existing .proto files for consistency.
• Implementing backwards-compatible changes and versioning.
• Configuring linting, codegen, or protobuf management (e.g., Buf).
• Mapping gRPC to REST endpoints with google.api.http annotations.

Best practices

• Use resource-oriented design: canonical resource name in a name field and google.api.resource annotations for type patterns.
• Follow snake_case for field names, PascalCase for messages/enums, and include an _UNSPECIFIED zero enum value.
• Never renumber or reuse field tags; use reserved to block deprecated tags and names.
• Annotate field behavior (REQUIRED, OUTPUT_ONLY, IMMUTABLE) and prefer optional fields for presence semantics.
• Design RPCs per standard methods (Get/List/Create/Update/Delete) and use FieldMask for partial updates.
• Document semantics, idempotency, retry behavior, and authorization in proto comments.

Example use cases

• Designing a new resource API with list/get/create/update/delete RPCs and HTTP mappings.
• Refactoring a large message to split repeated or optional concerns without breaking clients.
• Adding server-populated timestamps and marking them OUTPUT_ONLY with google.protobuf.Timestamp.
• Introducing pagination and filtering to an existing list method using page_size and page_token.
• Preparing proto files for multi-language code generation and CI linting with Buf.