Contract
- Input: service interface requirements, data shapes, transport constraints, and client ecosystems.
- Output: service contract design with proto definitions, streaming plan, and gateway configuration.
- Scope: stay within the skill's declared boundaries; do not broaden without explicit direction.
- Rule: documented standards override defaults; explicit project rules take precedence.
- Rule: if blocked by missing context or dependencies, surface the blocker before proceeding.
Provenance
| Question |
Answer |
| What is the source of truth? |
The user's request, originating spec/issue, and the skill's declared outputs |
| What is in scope? |
Work covered by the skill's acceptance criteria and completion rules |
| What is explicitly out of scope? |
Files, behaviors, and decisions outside the skill's declared boundary |
| Who or what consumes this artifact afterward? |
The next skill in the workflow or the user |
| What evidence proves it is done? |
Completion criteria met, artifact saved, validation passed |
| What risk remains? |
Subjective judgment calls, missing context, or external dependency failures |
Artifact
Emit GrpcConnectArtifact as both:
- JSON:
.agents/skills/platform/artifacts/grpc-connect/{identifier}.json
- Markdown view: same filename with
.md extension
gRPC and Connect
Use this skill when designing gRPC services, ConnectRPC APIs, or gRPC-to-REST gateway layers — protobuf contracts, streaming patterns, code generation, and cross-language compatibility.
Process
1. Define service and method surface
- List RPC methods: unary, server streaming, client streaming, or bidirectional.
- Assign method semantics: idempotent, safe, retriable, or side-effecting.
- Group methods into services by domain boundary and ownership.
Completion criterion: service surface documented with method semantics.
2. Design protobuf schema
- Define
.proto file structure: packages, imports, message types, enums.
- Choose field numbering strategy to leave room for future fields.
- Define
google.protobuf well-known types where applicable (Timestamp, Duration, Struct).
Completion criterion: proto schema documented with field numbering and type choices.
3. Plan versioning and compatibility
- Define backward-compatible evolution rules: additive fields only, reserved field numbers for removed fields.
- Choose wire compatibility testing strategy.
- Document how consumers detect schema changes (reflection, descriptor sets, or version headers).
Completion criterion: versioning and compatibility rules documented.
4. Design streaming and long-running operations
- Choose streaming type per use case: server streaming for feeds, client streaming for ingestion, bidi for chat or sync.
- Define flow-control, backpressure, and cancellation semantics.
- Plan timeout and keepalive for long-running streams.
Completion criterion: streaming design documented with flow control and timeout behavior.
5. Configure ConnectRPC and gateway
- Choose transport layer: pure gRPC, ConnectRPC (HTTP/JSON + gRPC), or both.
- Design
grpc-gateway annotations for REST mapping if dual-protocol is needed.
- Define error mapping: gRPC status codes to HTTP status codes for REST clients.
Completion criterion: transport and gateway configuration documented.
6. Plan code generation and CI
- Define generator pipeline: protoc plugins for Go, TypeScript, Python, etc.
- Set up generated code versioning and CI validation.
- Document client SDK packaging and distribution strategy.
Completion criterion: code generation pipeline and CI integration documented.
Rules
- Rule: never reuse field numbers; reserve removed numbers immediately.
- Rule: treat proto files as public API contracts; review changes with the same rigor as REST API changes.
- Rule: use packages and import boundaries to prevent schema sprawl across teams.
- Rule: document retry budgets, idempotency keys, and safe-for-retry semantics per method.
- Rule: enable reflection and health checking for operational visibility.
- Rule: validate proto files in CI with linter, breaking-change detector, and code generation check.
Completion
- the skill's completion criteria are explicitly checked
- the artifact is saved and validated
- any blockers or skipped validations are documented
- the next consumer is identified or the work is handed off
@include .agents/skills/platform/contract-base.xml
1---2name: "grpc-connect"3category: "backend"4maturity: "stable"5version: "1"6description: "gRPC and Connect (protobuf, ConnectRPC, grpc-gateway, streaming, code generation)."7license: "MIT"8capabilities:9 - apply grpc connect methods within explicit backend boundaries10 - analyze grpc and connect (protobuf, connectrpc, grpc-gateway, streaming, code generation) with assumptions, constraints, and failure modes11 - produce and validate a backend artifact with evidence, decisions, and next steps12outputs: "service contract design with proto definitions, streaming plan, and gateway configuration."13sideEffects: []14dependencies: []15stopCondition: "gRPC/Connect design complete; artifact saved; completion criteria checked."16risk: "medium"17trustTier: "3"18maxIterations: "6"19promptVersion: "2.0"20artifactType: "backend"21modelTier: "reasoning"22evaluators: ["behavioral", "regression"]23fixturesPath: .agents/skills/platform/fixtures/behavioral/grpc-connect.json24diataxis: "how-to"25tags: ["backend"]26compatibility: []27approvalRequired: "true"28approvalFor: []29metadata:30 source: https://skillmd.com/skills/quantumquirkxyz/grpc-connect31---3233## Contract3435- Input: service interface requirements, data shapes, transport constraints, and client ecosystems.36- Output: service contract design with proto definitions, streaming plan, and gateway configuration.37- Scope: stay within the skill's declared boundaries; do not broaden without explicit direction.38- Rule: documented standards override defaults; explicit project rules take precedence.39- Rule: if blocked by missing context or dependencies, surface the blocker before proceeding.4041## Provenance4243| Question | Answer |44|---|---|45| What is the source of truth? | The user's request, originating spec/issue, and the skill's declared outputs |46| What is in scope? | Work covered by the skill's acceptance criteria and completion rules |47| What is explicitly out of scope? | Files, behaviors, and decisions outside the skill's declared boundary |48| Who or what consumes this artifact afterward? | The next skill in the workflow or the user |49| What evidence proves it is done? | Completion criteria met, artifact saved, validation passed |50| What risk remains? | Subjective judgment calls, missing context, or external dependency failures515253## Artifact5455Emit `GrpcConnectArtifact` as both:56- JSON: `.agents/skills/platform/artifacts/grpc-connect/{identifier}.json`57- Markdown view: same filename with `.md` extension585960# 61# 62# gRPC and Connect6364Use this skill when designing gRPC services, ConnectRPC APIs, or gRPC-to-REST gateway layers — protobuf contracts, streaming patterns, code generation, and cross-language compatibility.656667## Process6869### 1. Define service and method surface70- List RPC methods: unary, server streaming, client streaming, or bidirectional.71- Assign method semantics: idempotent, safe, retriable, or side-effecting.72- Group methods into services by domain boundary and ownership.7374**Completion criterion:** service surface documented with method semantics.7576### 2. Design protobuf schema77- Define `.proto` file structure: packages, imports, message types, enums.78- Choose field numbering strategy to leave room for future fields.79- Define `google.protobuf` well-known types where applicable (Timestamp, Duration, Struct).8081**Completion criterion:** proto schema documented with field numbering and type choices.8283### 3. Plan versioning and compatibility84- Define backward-compatible evolution rules: additive fields only, reserved field numbers for removed fields.85- Choose wire compatibility testing strategy.86- Document how consumers detect schema changes (reflection, descriptor sets, or version headers).8788**Completion criterion:** versioning and compatibility rules documented.8990### 4. Design streaming and long-running operations91- Choose streaming type per use case: server streaming for feeds, client streaming for ingestion, bidi for chat or sync.92- Define flow-control, backpressure, and cancellation semantics.93- Plan timeout and keepalive for long-running streams.9495**Completion criterion:** streaming design documented with flow control and timeout behavior.9697### 5. Configure ConnectRPC and gateway98- Choose transport layer: pure gRPC, ConnectRPC (HTTP/JSON + gRPC), or both.99- Design `grpc-gateway` annotations for REST mapping if dual-protocol is needed.100- Define error mapping: gRPC status codes to HTTP status codes for REST clients.101102**Completion criterion:** transport and gateway configuration documented.103104### 6. Plan code generation and CI105- Define generator pipeline: protoc plugins for Go, TypeScript, Python, etc.106- Set up generated code versioning and CI validation.107- Document client SDK packaging and distribution strategy.108109**Completion criterion:** code generation pipeline and CI integration documented.110111## Rules112113- Rule: never reuse field numbers; reserve removed numbers immediately.114- Rule: treat proto files as public API contracts; review changes with the same rigor as REST API changes.115- Rule: use packages and import boundaries to prevent schema sprawl across teams.116- Rule: document retry budgets, idempotency keys, and safe-for-retry semantics per method.117- Rule: enable reflection and health checking for operational visibility.118- Rule: validate proto files in CI with linter, breaking-change detector, and code generation check.119120## Completion121122- the skill's completion criteria are explicitly checked123- the artifact is saved and validated124- any blockers or skipped validations are documented125- the next consumer is identified or the work is handed off126---127@include .agents/skills/platform/contract-base.xml