proto-split

Split multi-service protobuf files into one .proto per service with shared types.

4|1|Updated Apr 12, 2026
One-click install
npx skills add https://github.com/reliant-labs/forge --skill proto-split
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: proto-split
Source: https://github.com/reliant-labs/forge/tree/main/internal/templates/project/skills/forge/proto-split
Command: npx skills add https://github.com/reliant-labs/forge --skill proto-split

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

You have a single .proto file that incorrectly contains multiple service definitions, which makes forge lint fail and causes ambiguous generation outputs and tight cross-service coupling.

Core Features & Use Cases

  • Identify what to split by inventorying services, RPCs, and message ownership, then classifying messages as service-owned, shared, or removable.
  • Restructure the proto layout into one service per .proto plus an optional shared types file for cross-service value messages.
  • Update build and configuration by fixing imports, adjusting forge.yaml services entries, moving handler code, and regenerating code so lint/build/test stay green.

Quick Start

Run the split plan for your aggregated proto by creating proto/shared/v1/types.proto for truly shared messages and then moving each service into its own proto/services/<service>/v1 file before updating forge.yaml and regenerating with forge generate.

Frequently Asked Questions about proto-split

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I split a multi-service protobuf file into separate proto files?

To split a multi-service protobuf file, you inventory services and messages, classify them, then create one .proto per service and extract shared value types into a shared file to reduce cross-service coupling.

Why does forge lint fail when multiple gRPC services are defined in one proto file?

Forge lint fails because it enforces single service declarations per file. When a proto contains multiple service definitions, it causes ambiguous generation outputs and tight cross-service coupling, requiring you to split the proto layout.

How do I handle shared message types when splitting protos by service boundary?

When splitting protos by service boundary, you classify messages as service-owned, shared, or removable. Truly shared cross-service value messages are extracted into a shared types file, such as proto/shared/v1/types.proto, to prevent duplication.

Do I need to update forge.yaml after splitting proto files into separate services?

Yes, you must update forge.yaml with snake-form path service entries after splitting proto files. You also need to fix imports, move handler code, and regenerate code using forge generate instead of editing generated pb.go artifacts.

What is the best way to reduce cross-service coupling in legacy protobuf definitions?

The best way to reduce cross-service coupling is to restructure legacy proto layouts into one service per file, extract shared types, forbid service-to-service proto imports, and enforce single service declarations per file during code generation.