public-grpc-api-design Skill (samber): Public gRPC API Design

Makes Claude decide whether your gRPC services should be public, then design the proto conventions, error model and gateway.

Installs: 9.4K; on skills.sh
Stars: 9; on GitHub
Files: 4; besides SKILL.md
Updated: Nov 2026; last repo commit

public-grpc-api-design makes Claude design a public gRPC surface for external developers. It starts with a when-gRPC gate, then covers proto package and versioning conventions, breaking-change gates, streaming, the google.rpc.Status error model, transcoding for non-gRPC clients and an exposure audit.

It starts when you mention gRPC, protobuf or .proto files, buf, Connect-RPC, grpc-gateway or gRPC-JSON transcoding at a public edge. Claude asks 6 opening questions, then works through 7 steps. SKILL.md says it is a design layer, not language-specific server implementation. The skill bundles no scripts.

Good for

Platform teams asked to expose internal gRPC services to partners
API owners setting proto package and versioning rules
Teams putting Connect-RPC in front of a gRPC backend for browsers

Install public-grpc-api-design

Claude Code

Copy this prompt.

Install the public-grpc-api-design skill in Claude Code. Run this command:

/plugin marketplace add samber/developer-platform-skills
/plugin install developer-platform-skills@developer-platform-skills

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both, or you get every skill twice. The README asks you to install the whole set, not just public-grpc-api-design, because the skills reference each other and a lone skill leaves those hand-offs with nowhere to go. The plugin adds all 61 skills in the repo (counted from the repo tree). Its manifests list no hooks, agents or MCP servers.

From the project README. Source.

What's in the skill

When it loads

Design a public gRPC surface for external developers - the when-gRPC-at-all gate (most platforms keep gRPC internal and publish REST or transcoded JSON), AIP proto package and versioning conventions, buf breaking-change gates and their google.api.http blind spot, unary-by-default streaming decisions, the google.rpc.Status error model with its HTTP-mapping traps, transcoding and gateway architecture (Connect-RPC, grpc-gateway, Envoy), and external auth and TLS. Use whenever the user mentions gRPC, protobuf or .proto files, buf, Connect-RPC, grpc-gateway, or gRPC-JSON transcoding at a public edge - even if they never say "gRPC API design". Design layer only, not language-specific server implementation.

Sections in SKILL.md

Clarifying questions
Consumer types
Workflow
1. The when-gRPC gate
2. Proto package and versioning conventions
3. Breaking-change gates
4. Streaming posture: unary by default
5. Error model: google.rpc.Status mechanics
6. Transcoding and gateway architecture
7. External auth, TLS, and the exposure audit
Failure modes
Measurement
Invocation examples
References

Key facts

Author: Samuel Berthe
License: MIT
Version: 1.0.2
Installs on skills.sh: 9,360 (Nov 2, 2026)
GitHub stars: 9 (Nov 2, 2026)
skills.sh audits: Gen Agent Trust Hub pass; Socket pass; Snyk pass (Nov 2, 2026)
Last repo commit: Nov 1, 2026
What installs: 5 files including SKILL.md: evals/evals.json and 3 reference files. It bundles no scripts.
Needs: The other skills in the repo; the README says to install the whole set
Works in: Claude Code, Claude.ai, Codex, Cursor, Gemini CLI, and other agents through the skills CLI

What it includes

Asks 6 questions in one batch before designing anything.
Try: “Our platform team wants to expose our internal gRPC services to partners - design the public surface and tell us whether that's even the right move.”
Opening questions
Decides whether gRPC should be public at all; dual-stack is the common answer.
The when-gRPC gate
Follows Google AIP style, with one package per API ending in a major version.
Proto package and versioning conventions
Makes buf breaking and buf lint hard CI gates on every PR.
Breaking-change gates
Exposes unary calls by default and records each streaming method as a decision.
Streaming posture
Uses google.rpc.Status and flags two traps on public surfaces.
Error model
Compares raw public gRPC, grpc-gateway, Envoy transcoder and Connect-RPC.
Transcoding and gateway architecture
Starts with TLS and audits the service for admin or debug calls before launch.
External auth, TLS and the exposure audit
Advises saving decisions to developer-platform-context.md when memory is a file.
Write · Remember decisions (optional)

From the official docs

Permissions

Low risk

This skill is written advice that bundles no scripts. The one thing it may write is a decisions file, so check what Claude saves.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It may save decisions to a file
SKILL.md advises using developer-platform-context.md when memory lives in a file, and calls it an advisory reference. Check or delete that file if you do not want decisions kept. github.com
The plugin route adds all 61 skills
The README asks you to install every skill in the repo, and the repo has 61. The plugin manifests list no hooks, agents or MCP servers, and the repo tree holds none. github.com
Folder holds Markdown and one JSON file
This skill's folder has 5 files: SKILL.md, evals/evals.json and 3 reference files. It has no .py, .sh or .js file. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No read-only setting is documented. Decline the memory-file suggestion if you want no files written.
Scopes	Asks you opening questions and works from your answers and anything you share, such as specs or docs May save settled decisions to a file named developer-platform-context.md if your memory lives in a file

Questions

How do I install public-grpc-api-design?

Use the install box above. The README asks you to install all 61 skills in the repo, not just this one, because the skills point to each other. In Claude Code that is the plugin route, and elsewhere the skills CLI or the client's own route installs the set.

Does public-grpc-api-design work in Claude.ai, Codex or Cursor?

The README documents installs for Claude.ai, Claude Code, Codex, Cursor and Gemini CLI. It also lists the skills CLI, which it calls universal for Agent Skills-compatible tools. The Claude.ai route adds the whole repo as a plugin marketplace.

Does it need an API key or any setup?

SKILL.md sets no environment variable and the folder bundles no scripts. It does ask for details of your own API or product in its opening questions.

Is public-grpc-api-design safe to use?

The folder holds Markdown and one JSON file, and no scripts. SKILL.md does suggest saving settled decisions to developer-platform-context.md when your memory lives in a file, so check what Claude writes. Our advice: treat the design it produces as a draft for your team to review before you publish it.

public-grpc-api-design vs api-error-design?

This skill owns the gRPC-native mechanics of google.rpc.Status and two traps on public surfaces. SKILL.md leaves taxonomy philosophy, such as code catalogs, message writing and retryability signaling, to api-error-design.

Should we expose gRPC publicly at all?

SKILL.md says practitioner consensus favors dual-stack: gRPC inside where you control both ends, and REST or transcoded JSON at the edge. Browsers cannot speak gRPC's HTTP/2 framing, so any browser consumer makes a proxy layer mandatory.

Information

updated Nov 2, 2026

Repository: samber/developer-platform-skills
Folder: skills/public-grpc-api-design

samber/developer-platform-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

README · github.com
public-grpc-api-design SKILL.md · github.com
public-grpc-api-design folder · github.com
api-error-design SKILL.md · github.com
marketplace.json · github.com
plugin.json · github.com