dirien/yet-another-agent-harness / .claude/skills/agent-ready-go
agent-ready-go
VerifiedPrepares Go applications to work effectively with AI coding agents. Use when setting up a new Go project or retrofitting an existing one to ensure: structured JSON logging (slog/Zap/ZeroLog/Logrus), machine-readable command output, thorough golangci-lint configuration, non-interactive CLI design with --yes flags, structured error handling with meaningful exit codes, proper context.Context propagation, graceful shutdown, health check endpoints, and a standardized Makefile. Triggers when a user asks to make their Go app "agent-ready," "AI-friendly," wants to improve agent tooling/observability in a Go project, or needs to audit an existing Go project against agent-readiness best practices.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.3 KB |
| assets/Makefile | other | 2.5 KB |
| references/config.md | markdown | 4.0 KB |
| references/error-handling.md | markdown | 5.6 KB |
| references/logging.md | markdown | 7.1 KB |
| references/non-interactive.md | markdown | 4.8 KB |
| references/services.md | markdown | 5.8 KB |
| references/testing.md | markdown | 6.5 KB |
references/services.md
View on GitHub<!-- Copyright 2025-2026 Richard Shade. Licensed under Apache-2.0. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
# HTTP Service Patterns for Agent-Ready Go
## Graceful Shutdown
Services that don't handle SIGTERM drop in-flight requests when containers
restart. Use `signal.NotifyContext` to listen for OS signals, then call
`srv.Shutdown` to drain connections before exiting:
```go
package main
import (
"context"
"errors"
"fmt"
"log/slog"
"net/http"
"os"
"os/signal"
"syscall"
"time"
)
func main() {
srv := &http.Server{
Addr: ":8080",
Handler: buildRouter(),
}
// Start server in a goroutine so main can wait for shutdown signal.
go func() {
slog.Info("server listening", slog.String("addr", srv.Addr))
if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
fmt.Fprintf(os.Stderr, "server error: %v\n", err)
os.Exit(1)
}
}()
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
defer stop()
<-ctx.Done()
slog.Info("shutdown signal received")
shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
fmt.Fprintf(os.Stderr, "graceful shutdown failed: %v\n", err)
os.Exit(1)
}
slog.Info("server stopped cleanly")
}
```
## Health Check Endpoints
Expose `/healthz` (liveness) and `/readyz` (readiness) on every HTTP service.
Kubernetes and load balancers use these to route traffic:
- **liveness** (`/healthz`) — is the process alive and not deadlocked?
- **readiness** (`/readyz`) — is the process ready to serve traffic (DB
connected, caches warm)?
```go
type HealthResponse struct {
Status string `json:"status"` // "ok" | "degraded" | "down"
Version string `json:"version"`
Checks map[string]string `json:"checks,omitempty"` // "db": "ok", "cache": "degraded"
}
func livenessHandler(version string) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(HealthResponse{
Status: "ok",
Version: version,
})
}
}
func readinessHandler(db *sql.DB, version string) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
checks := map[string]string{}
status := "ok"
if err := db.PingContext(r.Context()); err != nil {
checks["db"] = "down"
status = "down"
} else {
checks["db"] = "ok"
}
code := http.StatusOK
if status == "down" {
code = http.StatusServiceUnavailable
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(code)
_ = json.NewEncoder(w).Encode(HealthResponse{
Status: status,
Version: version,
Checks: checks,
})
}
}
```
Register them on a dedicated internal mux so they are never blocked by
authentication middleware:
```go
mux.HandleFunc("/healthz", livenessHandler(version))
mux.HandleFunc("/readyz", readinessHandler(db, version))
```
## Request ID Middleware
Propagate `X-Request-ID` through every request so logs, traces, and error
responses can be correlated across services. Generate a UUID if the header is
absent:
```go
import (
"context"
"log/slog"
"net/http"
"github.com/google/uuid"
)
type requestIDKey struct{}
func RequestIDMiddleware(log *slog.Logger, next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
id := r.Header.Get("X-Request-ID")
if id == "" {
id = uuid.New().String()
}
w.Header().Set("X-Request-ID", id)
ctx := context.WithValue(r.Context(), requestIDKey{}, id)
reqLog := log.With(slog.String("request_id", id))
next.ServeHTTP(w, WithLogger(ctx, reqLog))
})
}
func RequestIDFromContext(ctx context.Context) string {
if id, ok := ctx.Value(requestIDKey{}).(string); ok {
return id
}
return ""
}
```
Install:
```bash
go get github.com/google/uuid
```
## OpenTelemetry Tracing
Add distributed tracing so agents and operators can follow a request across
service boundaries.
Install dependencies:
```bash
go get go.opentelemetry.io/otel
go get go.opentelemetry.io/otel/sdk/trace
go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc
```
Initialize the tracer provider at startup:
```go
import (
"context"
"log/slog"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
"go.opentelemetry.io/otel/propagation"
sdktrace "go.opentelemetry.io/otel/sdk/trace"
)
func initTracer(ctx context.Context, serviceName string) (func(context.Context) error, error) {
exp, err := otlptracegrpc.New(ctx)
if err != nil {
return nil, err
}
tp := sdktrace.NewTracerProvider(
sdktrace.WithBatcher(exp),
sdktrace.WithResource(newResource(serviceName)),
)
otel.SetTracerProvider(tp)
otel.SetTextMapPropagator(propagation.TraceContext{})
return tp.Shutdown, nil
}
```
Instrument a handler with a span:
```go
tracer := otel.Tracer("order-service")
func (h *OrderHandler) Create(w http.ResponseWriter, r *http.Request) {
ctx, span := tracer.Start(r.Context(), "HandleCreateOrder")
defer span.End()
// Attach trace/span IDs to log lines for correlation.
sc := span.SpanContext()
logger.FromContext(ctx).Info("handling request",
slog.String("trace_id", sc.TraceID().String()),
slog.String("span_id", sc.SpanID().String()),
)
// ... handler logic using ctx
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |