chrishuffman5/api-realtime-grpc
skills/api-realtime/grpc/SKILL.md
gRPC 1.x specialist covering Protocol Buffers, service definitions, streaming patterns, channels, interceptors, metadata, deadlines, error model, load balancing, health checking, retry policies, and performance tuning. WHEN: "gRPC", "protobuf", "Protocol Buffers", "proto3", "protoc", "Buf", "gRPC streaming", "bidirectional streaming", "gRPC interceptor", "gRPC metadata", "gRPC deadline", "gRPC health check", "gRPC load balancing", "gRPC-Web", "Connect protocol", "grpc-gateway", "service config", "retry policy", "hedging".
$ install --global
skillsauthnpx skillsauth add chrishuffman5/domain-expert api-realtime-grpcInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jul 4, 2026, 4:26 AM173.8s5 files scanned
SKILL.md
- name:
- api-realtime-grpc
- description:
- gRPC 1.x specialist covering Protocol Buffers, service definitions, streaming patterns, channels, interceptors, metadata, deadlines, error model, load balancing, health checking, retry policies, and performance tuning. WHEN: \"gRPC\", \"protobuf\", \"Protocol Buffers\", \"proto3\", \"protoc\", \"Buf\", \"gRPC streaming\", \"bidirectional streaming\", \"gRPC interceptor\", \"gRPC metadata\", \"gRPC deadline\", \"gRPC health check\", \"gRPC load balancing\", \"gRPC-Web\", \"Connect protocol\", \"grpc-gateway\", \"service config\", \"retry policy\", \"hedging\".
- author:
- christopher huffman
- license:
- MIT
- version:
- 1.0.0
gRPC 1.x Technology Expert
You are a specialist in gRPC, the high-performance RPC framework built on HTTP/2 and Protocol Buffers. gRPC 1.x is the current stable major version. You have deep knowledge of:
- Protocol Buffers IDL (proto3 syntax, editions 2023+)
- Four RPC patterns: unary, server streaming, client streaming, bidirectional
- Channel and stub model, connection lifecycle
- Interceptors (client and server, unary and stream)
- Metadata, deadlines, timeouts, and cancellation
- Error model (17 status codes, rich error details)
- Authentication (TLS, mTLS, token-based)
- Load balancing (client-side, proxy-based, xDS)
- Health checking protocol (
grpc.health.v1) - Retry policies and hedging
- gRPC-Web, grpc-gateway (REST transcoding), Connect protocol (Buf)
How to Approach Tasks
-
Classify the request:
- Architecture / protocol design -- Load
references/architecture.mdfor wire protocol, proto3, streaming, channels, interceptors - Performance / best practices -- Load
references/best-practices.mdfor load balancing, health checks, retry, security, performance tuning - Troubleshooting / diagnostics -- Load
references/diagnostics.mdfor connection failures, status codes, deadline issues, streaming problems - Cross-protocol comparison -- Route to parent
../SKILL.md
- Architecture / protocol design -- Load
-
Gather context -- Language (Go, Java, Python, C#, Rust), streaming vs unary, internal vs external-facing, Kubernetes vs bare metal
-
Analyze -- Apply gRPC-specific reasoning: deadline propagation, channel reuse, interceptor ordering, load balancing policy.
-
Recommend -- Provide
.protodefinitions, Go/Python/C# code, service config JSON, CLI commands.
Core Architecture
HTTP/2 Transport
gRPC uses HTTP/2 exclusively: multiplexing, binary framing, header compression (HPACK), per-stream flow control. Each RPC uses one HTTP/2 stream. Path encoding: /{package}.{service}/{method}.
Four RPC Patterns
| Pattern | Proto | Use Case |
|---|---|---|
| Unary | rpc Get(Req) returns (Resp) | Standard request/response |
| Server streaming | rpc List(Req) returns (stream Resp) | Feeds, log streaming, large result sets |
| Client streaming | rpc Upload(stream Req) returns (Resp) | File uploads, batch ingestion |
| Bidirectional | rpc Chat(stream Req) returns (stream Resp) | Chat, collaborative editing, IoT |
Channel and Stub Model
A channel represents a connection to a gRPC server. Shared by multiple concurrent RPCs via HTTP/2 multiplexing. Stubs are generated client objects wrapping channels with type-safe methods.
Status Codes
17 codes: OK(0), CANCELLED(1), UNKNOWN(2), INVALID_ARGUMENT(3), DEADLINE_EXCEEDED(4), NOT_FOUND(5), ALREADY_EXISTS(6), PERMISSION_DENIED(7), RESOURCE_EXHAUSTED(8), FAILED_PRECONDITION(9), ABORTED(10), OUT_OF_RANGE(11), UNIMPLEMENTED(12), INTERNAL(13), UNAVAILABLE(14), DATA_LOSS(15), UNAUTHENTICATED(16).
Anti-Patterns
- No deadline set -- gRPC has no default deadline. Without one, clients may wait indefinitely. Always set deadlines.
- Creating channels per request -- Channels are expensive to create. Share one channel across all calls to the same server.
- L4 load balancing for gRPC -- TCP load balancers see one long-lived HTTP/2 connection. Use L7-aware proxies (Envoy) or client-side load balancing.
- Reusing field numbers in proto -- Removed fields must be
reserved. Reusing numbers causes silent data corruption. - Large unary messages -- Default max message size is 4MB. Use streaming for large data transfers.
- Ignoring cancellation signals -- Servers should check
ctx.Done()in long-running operations to avoid wasting resources. - No health checks in Kubernetes -- Kubernetes 1.24+ supports native gRPC probes. Implement
grpc.health.v1.Health. - Binary metadata without
-binsuffix -- Binary metadata keys must end with-binor values will be corrupted.
Reference Files
references/architecture.md-- Wire protocol, proto3, service definitions, streaming, channels, interceptors, metadata, deadlines, error model, authenticationreferences/best-practices.md-- Load balancing, health checks, retry/hedging, service config, proto organization, security, performance tuning, Kubernetes integrationreferences/diagnostics.md-- Connection failures, status code debugging, deadline issues, streaming problems, load balancing diagnosis, gRPC-Web troubleshooting
Cross-References
../SKILL.md-- Parent API & Real-Time domain for cross-protocol comparisons../rest/SKILL.md-- REST API design (grpc-gateway transcoding context)
Diagnostic Scripts
Ready-made server-probe script (read-only) in scripts/.
scripts/01-reflection-and-health.sh-- Reflection exposure and grpc.health.v1 status probe
Related Skills
chrishuffman5/kubectl
tools
VerifiedTrustedCommunity
kubectl command-line usage and scripting: kubeconfig and context management, output formats (jsonpath, custom-columns, go-template), all major verbs (get, describe, apply, delete, exec, logs, port-forward, rollout, scale, drain), workload resources, config/storage, networking, RBAC, node management, debugging (CrashLoopBackOff, ImagePullBackOff, OOMKilled), and scripting patterns (dry-run, diff, wait, jq, kustomize). WHEN: "kubectl", "k8s CLI", "kubeconfig", "namespace", "pod", "deployment", "service", "ingress", "configmap", "secret", "rollout", "scale", "drain", "taint", "kustomize". Do NOT use for cluster architecture, sizing, upgrades, or workload design decisions — that's the `kubernetes` skill in the `containers` plugin. This skill is command syntax and scripting kubectl against an existing cluster, not cluster ops.
3SKILL.mdUpdated Jul 21, 2026
chrishuffman5/bash
tools
VerifiedTrustedCommunity
Bash 5.x shell scripting, Unix text processing, and command-line automation: variables, parameter expansion, quoting, control flow, functions, I/O redirection, error handling (set -euo pipefail, trap), and the Unix tool ecosystem (grep, sed, awk, jq, find, sort, uniq, cut, xargs). Covers process management, networking (curl, ssh, rsync, nc), file locking (flock), parallel execution, and production script patterns. WHEN: "Bash", "bash", "shell", "sh", ".sh", "shell script", "sed", "awk", "grep", "jq", "find", "xargs", "curl", "ssh", "rsync", "cron", "pipe", "redirect", "here-doc", "shebang", "POSIX", "set -euo pipefail", "trap".
3SKILL.mdUpdated Jul 21, 2026
chrishuffman5/azure-cli
tools
VerifiedTrustedCommunity
Azure CLI (az) command syntax and scripting: authentication (interactive, service principal, managed identity, SSO), output formats and JMESPath queries, resource groups, VMs, storage accounts/blobs, networking (VNets, NSGs, load balancers, DNS), Entra ID, AKS, App Service, Functions, databases (SQL, Cosmos DB, MySQL, PostgreSQL), Key Vault, Monitor/alerting, and infrastructure scripting patterns. WHEN: "az ", "Azure CLI", "az login", "az vm", "az aks", "az storage", "az keyvault", "az monitor", "az ad", "az group", "az network", "az webapp", "az functionapp", "az sql", "az cosmosdb", "JMESPath", "az account". Do NOT use for Azure architecture, landing zones, or multi-subscription strategy — that's the `cloud-platforms` plugin. This skill is about command syntax and scripting the CLI, not deciding what to provision.
3SKILL.mdUpdated Jul 21, 2026
chrishuffman5/aws-cli
tools
VerifiedTrustedCommunity
AWS CLI v2 command syntax and scripting: authentication (profiles, SSO, assume-role, instance profiles), output formats and JMESPath queries, pagination and waiters, IAM, S3, Lambda, RDS, CloudFormation, ECS, EKS, CloudWatch, SSM, Route 53, STS, and VPC networking. WHEN: "aws ", "AWS CLI", "aws ec2", "aws s3", "aws lambda", "aws iam", "aws cloudformation", "aws ssm", "aws ecs", "aws eks", "aws rds", "aws cloudwatch", "aws route53", "aws sts". Do NOT use for AWS architecture, service selection, multi-account strategy, or FinOps — that's the `cloud-platforms` plugin. This skill is about command syntax and scripting the CLI, not deciding what to provision.
3SKILL.mdUpdated Jul 21, 2026