Use Buf Agent Skill

Use Buf

Use the Buf CLI as the source of truth for Protobuf compilation, dependency resolution, linting, breaking-change detection, and code generation.

Inspect Before Changing

• Read repository instructions.
• Search the repository root and likely API directories for buf.yaml, buf.lock, buf.gen.yaml, and buf.gen.<domain>.yaml files.
• Inspect the configuration version, module paths, dependency declarations, lint policy, breaking policy, inputs, plugin pins, output paths, and existing generation scripts.
• Run buf --version and check repository/CI tool pins before using features from a newer configuration schema.
• Diagnose configuration or dependency problems before changing .proto files to work around them.

Use one default buf.gen.yaml. Introduce buf.gen.<domain>.yaml only when generation products genuinely require isolated plugin sets, inputs, or outputs. Pass non-default templates explicitly with buf generate --template <file>.

Keep Configuration Responsibilities Clear

• Use buf.yaml for workspaces/modules, BSR dependencies, lint rules, breaking rules, policies, and Buf check plugins.
• Use buf.gen.yaml or buf.gen.<domain>.yaml for protoc-gen-* code-generation plugins, inputs, output directories, options, and managed mode.
• Use buf.lock as generated dependency resolution state. Do not edit it manually.
• Keep configuration in the repository root or the established API workspace directory unless repository structure requires otherwise.

Read references/configuration.md before adding modules, dependencies, check plugins, generation templates, or output paths.

Manage Dependencies Deliberately

• Prefer BSR modules for maintained dependencies, including Google APIs, well-known types, Protovalidate, and grpc-gateway annotations.
• Add or remove dependencies in buf.yaml, then run buf dep update and inspect the buf.lock diff.
• Use buf dep graph --format json to identify the resolved dependency chain.
• Use buf dep prune only after confirming an import is genuinely unused.
• When a type appears missing, inspect configuration and the lockfile, run buf dep update, then run buf build or buf generate to obtain the compiler's concrete import/type error.
• Never hardcode an operating system's Buf cache location. Export the pinned module with buf export when source inspection is required.

Required Validation

After changing first-party Protobuf or Buf configuration, MUST run:

buf lint
buf generate
buf breaking --against '.git#branch=main'

Also run buf format --diff or the repository's format check and all language-specific tests/type checks for generated outputs.

Do not skip the breaking check merely because a break is intentional. Run it, capture the violations, and report that the change is an approved experimental/unreleased break. If the repository does not have a main branch, report that exact baseline failure and resolve the intended integration baseline rather than silently omitting compatibility validation.

Diagnose in Dependency Order

• Confirm the current directory and discovered buf.yaml.
• Confirm module paths and import paths.
• Confirm dependencies and buf.lock with buf dep graph.
• Compile with buf build.
• Lint with buf lint.
• Generate with the selected template.
• Inspect plugin stderr, output collisions, and generated diffs.
• Run the breaking check against main.

Use $use-buf-plugins for remote/local plugin selection, offline generation, rate limits, or plugin wrappers. Read references/commands-and-troubleshooting.md for precise inspection commands and failure handling.