rsc-universal 0.1.1

package/skills/go/SKILL.md

@@ -0,0 +1,438 @@
+---
+name: go
+description: "Use when writing, reviewing, testing, securing, or shipping Go code or HTTP services - Go idioms (simplicity, useful zero value, accept-interfaces/return-structs, functional options, embedding), error wrapping with %w and errors.Is/As, goroutines/channels/context/errgroup concurrency, net/http with Go 1.22 routing, log/slog structured logging, graceful shutdown, cmd/-internal/-pkg/ layout, table-driven tests with httptest/-race/fuzz, and govulncheck/SQL-parametrization security. Triggers - \"write a Go service/handler\", \"review this Go code\", \"add tests\", \"fix a goroutine leak\", \"is this idiomatic Go\", .go files, go.mod, net/http, slog, chi, errgroup."
+tags: [go, golang, http, backend, service]
+recommends: [postgresdb, secure-coding, deployment]
+origin: risco
+---
+
+# Idiomatic Go services
+
+Write, review, test, secure, and ship idiomatic Go HTTP services.
+
+Targets **Go 1.22+** (Go 1.26 is the current stable release): enhanced `net/http` routing
+(`mux.HandleFunc("GET /users/{id}", h)` + `r.PathValue`), `log/slog` structured
+logging, and fixed loop-variable semantics (no more `tt := tt`).
+
+## When to use / When NOT to use
+
+**Use when:**
+
+- Authoring, reviewing, or testing any `.go` file.
+- Designing or wiring a Go HTTP API (`net/http`, chi, middleware, handlers).
+- Debugging concurrency: goroutine leaks, data races, deadlocks, context plumbing.
+- Structuring a Go module (`cmd/`, `internal/`, `pkg/`, constructor injection).
+- Hardening or shipping a Go binary (timeouts, TLS, `govulncheck`, graceful shutdown).
+
+**When NOT to use (delegate):**
+
+- Language-agnostic abuse/authz review, threat modeling, OWASP-class bugs -> `secure-coding`
+  (this skill keeps Go-specific controls: SQL params, server timeouts, `govulncheck`, TLS defaults).
+- Containerfile / k8s / CI pipeline authoring -> `deployment` (this skill ships only a Docker note + `ldflags`).
+- Recording per-project conventions in a workspace wiki -> `harness` (see "Project grounding" below).
+- Non-service Go (CLI tooling, codegen, ML): patterns apply, but the HTTP/production half is irrelevant.
+
+Go error handling and HTTP contract design (status-code taxonomy, REST resource naming) live
+**here**, not in a separate skill — this skill is the canonical authority for both in Go.
+
+## Decision rules
+
+Apply these on every Go edit:
+
+1. Clear over clever; return early, keep the happy path unindented.
+2. Accept interfaces, return concrete structs; define interfaces in the **consumer** package.
+3. Make the zero value useful; never ship a type that panics before a constructor runs.
+4. `context.Context` is the **first** param, never stored in a struct, never `nil` (use
+   `context.TODO()` while wiring).
+5. Wrap every crossed boundary with `fmt.Errorf("verb: %w", err)`; classify with
+   `errors.Is`/`errors.As`, never string-match messages.
+6. No package-level mutable state; inject dependencies through constructors.
+7. Every goroutine needs a known exit path (context or a closed channel); a started
+   goroutine you cannot stop is a leak.
+8. Validate at the boundary; parametrize every SQL query; set all server timeouts; run
+   `govulncheck` before shipping.
+9. Tests are table-driven with subtests; run `-race` in CI; treat `go vet`/`staticcheck`
+   failures as build failures.
+10. Pick value-or-pointer receiver per type and stay consistent; mutating / large /
+    contains-`sync` -> pointer.
+
+## Idioms
+
+**Useful zero value.** Design types so the zero value works before any constructor.
+
+```go
+// Good: zero-value Counter is ready; the zero-value mutex is unlocked. var b bytes.Buffer too.
+type Counter struct {
+	mu sync.Mutex
+	n  int
+}
+
+func (c *Counter) Inc() { c.mu.Lock(); c.n++; c.mu.Unlock() }
+
+// Bad: nil map field panics on first write (assignment to entry in nil map); hidden init step.
+type Registry struct{ items map[string]int }
+
+func (r *Registry) Add(k string) { r.items[k]++ } // panic if items was never make()'d
+```
+
+**Accept interfaces, return structs.** Return the concrete type; declare the interface
+where it is consumed.
+
+```go
+type UserStore interface { // declared in package service - only what it needs
+	GetUser(ctx context.Context, id string) (*User, error)
+}
+func NewService(s UserStore) *Service { return &Service{store: s} } // Good: return *Service
+// Bad: func NewService(s UserStore) UserStore - returning the interface hides the type.
+```
+
+**Functional options.** Defaults first, then apply options.
+
+```go
+type Server struct {
+	addr    string
+	timeout time.Duration
+	logger  *slog.Logger
+}
+type Option func(*Server)
+
+func WithTimeout(d time.Duration) Option { return func(s *Server) { s.timeout = d } }
+func WithLogger(l *slog.Logger) Option   { return func(s *Server) { s.logger = l } }
+
+func NewServer(addr string, opts ...Option) *Server {
+	s := &Server{addr: addr, timeout: 30 * time.Second, logger: slog.Default()} // defaults first
+	for _, opt := range opts {
+		opt(s)
+	}
+	return s
+}
+```
+
+Use a plain `Config` struct once options exceed ~5; options are for optional, composable
+tuning, not required fields.
+
+**Embedding for composition.** Embed to borrow a behavior, not to fake inheritance.
+
+```go
+// Good: the service gets .Info/.Error for free from the embedded logger.
+type Service struct {
+	*slog.Logger
+	store UserStore
+}
+// Bad: deep type trees (Base -> Middle -> Leaf) modeling "is-a" inheritance - avoid.
+```
+
+**Early return.** Invert the error and `return`; keep the happy path flat (no arrow code).
+
+```go
+// Good: each failure returns immediately; the success path is unindented.
+func save(ctx context.Context, u *User) error {
+	if u == nil {
+		return errors.New("nil user")
+	}
+	if err := validate(u); err != nil {
+		return fmt.Errorf("validate: %w", err)
+	}
+	return store.Put(ctx, u)
+}
+// Bad: if u != nil { if err := validate(u); err == nil { ... } else { ... } } - arrow code.
+```
+
+**No package-level mutable state.** Inject via constructor (`func New(db *sql.DB) *Server`),
+never a global `var db *sql.DB` opened in `init()` - globals couple everything and kill
+testability.
+
+**Go 1.22 loopvar.** Loop variables are per-iteration now. Stop emitting the workaround:
+inside `for _, tt := range tests` the line `// tt := tt` is obsolete - DELETE it.
+
+## Errors
+
+Go error handling is owned here — the sentinel/typed/wrap/classify model below is canonical.
+
+**Sentinel vs typed.** Sentinels for identity; typed errors for data.
+
+```go
+var ErrNotFound = errors.New("not found")         // sentinel: identity
+type ValidationError struct{ Field, Msg string }  // typed: carries data
+func (e *ValidationError) Error() string { return fmt.Sprintf("%s: %s", e.Field, e.Msg) }
+```
+
+**Wrap and classify.** Wrap with `%w`; never compare message strings.
+
+```go
+err := fmt.Errorf("find user %s: %w", id, ErrNotFound)
+if errors.Is(err, ErrNotFound) { /* sentinel match through the wrap chain */ }
+var verr *ValidationError
+if errors.As(err, &verr) { /* typed match: verr.Field, verr.Msg */ }
+joined := errors.Join(err1, err2) // 1.20+: aggregate; Is/As traverse both
+```
+
+**3-layer boundary (the canonical flow).** Repo wraps the driver sentinel into a domain
+sentinel; service passes it through; handler classifies once and maps to a status, logging
+only the unexpected.
+
+```go
+// repository: translate sql.ErrNoRows into a domain sentinel, keep the chain.
+func (r *Repo) GetUser(ctx context.Context, id string) (*User, error) {
+	var u User
+	err := r.db.QueryRowContext(ctx, "SELECT id, name FROM users WHERE id = $1", id).
+		Scan(&u.ID, &u.Name)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
+	}
+	if err != nil {
+		return nil, fmt.Errorf("query user %s: %w", id, err)
+	}
+	return &u, nil
+}
+
+// handler: classify once, map to HTTP status.
+func (h *Handler) getUser(w http.ResponseWriter, r *http.Request) {
+	u, err := h.svc.GetUser(r.Context(), r.PathValue("id"))
+	switch {
+	case err == nil:
+		writeJSON(w, http.StatusOK, u)
+	case errors.Is(err, ErrNotFound):
+		http.Error(w, "not found", http.StatusNotFound)
+	default:
+		slog.Error("get user", "err", err)
+		http.Error(w, "internal error", http.StatusInternalServerError)
+	}
+}
+```
+
+Full handler adapter (error-returning `apiHandler`) -> `references/http-services.md`.
+
+**`defer` + named return** to capture `Close()` errors:
+
+```go
+func read(name string) (err error) {
+	f, e := os.Open(name)
+	if e != nil {
+		return e
+	}
+	defer func() { err = errors.Join(err, f.Close()) }() // capture Close() into the return
+	return nil
+}
+```
+
+**Anti-patterns:** `if err.Error() == "not found"` (string match); `panic` for control flow;
+swallowing with `_ = err`.
+
+## Concurrency (essentials)
+
+Bound work with a context deadline; bound concurrency with `errgroup` — the derived `ctx`
+cancels siblings on first error, and `g.SetLimit(n)` caps in-flight goroutines:
+
+```go
+g, ctx := errgroup.WithContext(ctx)
+g.SetLimit(8)
+for _, id := range ids {
+	g.Go(func() error { return process(ctx, id) }) // Go 1.22+: no id := id needed
+}
+err := g.Wait()
+```
+
+Three rules cover most service code: every goroutine needs a known exit path (a started
+goroutine you cannot stop is a leak); an unbuffered `ch <- v` with no receiver after a cancel
+blocks forever, so buffer it and `select` on `ctx.Done()`; **run `-race` in CI**. Low-level
+needs map to `sync.Once` (lazy init), `sync.RWMutex` (read-heavy state), `sync/atomic`
+(`atomic.Int64` counters).
+
+Full implementations — context plumbing, channel/select patterns, leak detection, worker
+pools, pipelines, fan-in/out, semaphores, `singleflight`, and a `withRetry` helper (backoff +
+full jitter, `ctx`-aware, **never retries 4xx**) -> `references/concurrency.md`.
+
+## HTTP services (essentials)
+
+Go 1.22 routed mux — method and path live in the pattern; the `error`-returning adapter
+centralizes status mapping:
+
+```go
+mux := http.NewServeMux()
+mux.HandleFunc("GET /users/{id}", getUser) // 405 on wrong method, 404 on no match
+id := r.PathValue("id")                    // inside the handler
+
+type apiHandler func(http.ResponseWriter, *http.Request) error
+func (h apiHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	if err := h(w, r); err != nil { /* classify via errors.Is/As -> status + slog */ }
+}
+```
+
+Set **all four** `http.Server` timeouts (`ReadHeaderTimeout`, `ReadTimeout`, `WriteTimeout`,
+`IdleTimeout`) — an unbounded read is a Slowloris DoS. Graceful shutdown on signal:
+`signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)`, then `srv.Shutdown(shutdownCtx)`
+on `<-ctx.Done()`.
+
+Routing patterns, chi vs stdlib, the full middleware chain (request-id, slog, panic-recovery,
+timeout), config, timeout values, functional-options server, and JSON helpers ->
+`references/http-services.md`.
+
+## Project layout
+
+```text
+cmd/api/main.go        # entrypoint: wiring only
+internal/handler/      # HTTP adapters
+internal/service/      # business logic; defines the interfaces it needs
+internal/repository/   # data access (pgx); implements service interfaces
+internal/config/       # env parsing, validation
+pkg/                   # ONLY genuinely reusable, stable public API
+testdata/              # fixtures, golden files
+go.mod go.sum
+```
+
+Wire the layers with **constructor injection**, outermost depends inward:
+`repo := repository.New(db); svc := service.New(repo); h := handler.New(svc)`.
+
+Package naming: short, lowercase, no underscores, no `util`/`common`, avoid stutter
+(`user.User`, not `user.UserStruct`). Interfaces live on the **consumer side**: the
+`service` package declares `UserStore`; the `repository` package implements it without
+importing the interface.
+
+## Testing (essentials)
+
+Table-driven with subtests and parallelism:
+
+```go
+func TestParse(t *testing.T) {
+	tests := []struct {
+		name    string
+		in      string
+		wantErr error
+	}{
+		{"ok", "42", nil},
+		{"bad", "x", ErrInvalid},
+	}
+	for _, tt := range tests { // Go 1.22+: no tt := tt needed
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			_, err := Parse(tt.in)
+			if !errors.Is(err, tt.wantErr) { // classify, not just != nil
+				t.Fatalf("got %v, want %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+```
+
+HTTP handlers via `httptest`: `req := httptest.NewRequest("GET", "/users/1", nil)`;
+`w := httptest.NewRecorder()`; `h.ServeHTTP(w, req)`; then assert on `w.Code` / `w.Body`.
+
+Use `t.Helper()` in assertions, `t.TempDir()` for files, `t.Cleanup()` for teardown,
+`t.Setenv()` for env. Run `go test -race -cover ./...`. Stdlib `testing` is the default;
+reach for `testify/require` only for deep-equality or large suites.
+
+Golden files, fuzzing, benchmarks, httptest matrices, interface fakes ->
+`references/testing.md`.
+
+## Security (embedded)
+
+Parametrize SQL (PostgreSQL; prefer `pgx v5` over `database/sql`); cap request bodies and reject unknown
+fields; set a TLS floor and trust the `crypto/tls` defaults:
+
+```go
+// Good                                       // Bad: string interpolation = SQL injection.
+db.QueryContext(ctx, "... WHERE id = $1", id) // db.QueryContext(ctx, fmt.Sprintf("... '%s'", id))
+
+r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1 MiB cap
+dec := json.NewDecoder(r.Body)
+dec.DisallowUnknownFields()
+
+tlsCfg := &tls.Config{MinVersion: tls.VersionTLS12} // do not hand-pick cipher suites
+```
+
+**Server timeouts** are a DoS control - set all four (see HTTP services above).
+
+Run `govulncheck ./...` in CI; keep deps honest with `go mod tidy` + `go mod verify`. Read
+secrets from env / a secret manager, never log them; redact tokens with slog `ReplaceAttr`.
+Deeper authz/abuse review -> `secure-coding`.
+
+## Production
+
+Wire `log/slog` JSON in `main` (level from env), then `slog.SetDefault`:
+
+```go
+logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: lvl}))
+slog.SetDefault(logger)
+```
+
+Stamp the version with `ldflags` and read module info at runtime:
+
+```bash
+go build -ldflags "-X main.version=$(git describe --tags --always)" ./cmd/api
+# at runtime: if info, ok := debug.ReadBuildInfo(); ok { slog.Info("build", "go", info.GoVersion) }
+```
+
+Mount `net/http/pprof` on a **separate internal** mux/port (never the public listener);
+expose `/healthz` (static 200 liveness) and `/readyz` (calls `db.PingContext` with a short
+timeout, 503 on failure). Graceful shutdown as shown above.
+
+Docker note: distroless/static base, `CGO_ENABLED=0`, multi-stage build. Full Containerfile
+-> `deployment`.
+
+## Anti-patterns / rationalizations -> STOP
+
+| Rationalization | Reality / Do instead |
+| --- | --- |
+| "I'll store ctx in the struct to avoid threading it" | No. `ctx` is the first arg of every call. |
+| "`_ = err` here, it can't fail" | Handle, log, or document why; `errcheck` catches it. |
+| "string-compare the error message" | `errors.Is`/`errors.As`; messages are not API. |
+| "global `db`/`logger` is simpler" | Inject via constructor; globals kill testability. |
+| "fire the goroutine, it'll finish" | Unbounded/unstoppable goroutine = leak; give it ctx + buffer. |
+| "I'll add `tt := tt` to be safe" | Go 1.22 fixed loopvar; it's noise now. |
+| "interface in the provider package, return the interface" | Return structs; interface lives with the consumer. |
+| "no timeouts, the LB handles it" | Set all four `http.Server` timeouts; Slowloris is real. |
+| "`panic` for this bad input" | Return an error; panic only for programmer bugs / `main` wiring. |
+| "skip `-race`, tests pass" | Race bugs are silent; `-race` in CI is mandatory. |
+| "`fmt.Sprintf` into SQL, the input's trusted" | Parametrize ($1...); trust nothing at the boundary. |
+| "testify everywhere" | Stdlib first; reach for testify only when it earns its weight. |
+
+## Quick reference
+
+| Task | Idiom / command |
+| --- | --- |
+| Format | `gofmt -w .` / `goimports -w .` |
+| Vet | `go vet ./...` |
+| Lint | `staticcheck ./...` / `golangci-lint run` |
+| Test (race+cover) | `go test -race -cover ./...` |
+| Fuzz | `go test -fuzz=Fuzz -fuzztime=30s` |
+| Vulns | `govulncheck ./...` |
+| Wrap error | `fmt.Errorf("verb: %w", err)` |
+| Classify error | `errors.Is` / `errors.As` |
+| Route | `mux.HandleFunc("GET /p/{id}", h)` + `r.PathValue("id")` |
+| Log | `slog.Info("msg", "key", val)` |
+| Shutdown | `signal.NotifyContext` + `srv.Shutdown(ctx)` |
+| Leak guard | buffered chan + `select { case ch<-v: case <-ctx.Done(): }` |
+| Local gate | `./scripts/verify.sh` (run in your module root) |
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+When this skill runs in a project with a `02-DOCS/` layer (the
+[`harness`](../harness/SKILL.md) Karpathy wiki), record this
+project's service decisions there and index them from the root `CLAUDE.md`, so the next
+agent inherits the conventions instead of re-deriving them.
+
+1. **Find the article** `02-DOCS/wiki/stack/go.md`, linked from a `## Knowledge map` section in the root
+   `CLAUDE.md`.
+2. **If missing or stale**, create/update it with the project's real choices — the project layout, the router (stdlib 1.22 / chi), the error and `slog` logging conventions, and concurrency/timeout defaults —
+   then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section, and
+   `CLAUDE.md` itself, if absent).
+3. **Read it first on every use** and stay consistent; when a convention changes, update the
+   article (bump its `Updated` date) in the same change.
+
+No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Unlike the
+brand study, technical conventions are *recorded, not gated* — never block the task on this.
+
+## See Also
+
+Sibling skills (all resolve under `skills/`):
+
+- [`secure-coding`](../secure-coding/SKILL.md) - threat modeling and language-agnostic authz/abuse/OWASP review (this skill keeps the Go-specific controls).
+- [`deployment`](../deployment/SKILL.md) - Docker multi-stage, GitHub Actions CI, Coolify/Vercel/Hetzner shipping (this skill ships only the Docker note + `ldflags`).
+- [`harness`](../harness/SKILL.md) - the `02-DOCS/` workspace wiki where per-project Go conventions are recorded (see "Project grounding").
+
+Local references (read when):
+
+- `references/concurrency.md` - goroutines, channels, errgroup, leaks, race detector.
+- `references/http-services.md` - routing, middleware, slog, graceful shutdown, full skeleton.
+- `references/testing.md` - table tests, httptest, fakes, golden files, fuzz, benchmarks.

package/skills/go/evals/README.md

@@ -0,0 +1,56 @@
+# Eval harness — `go` skill
+
+These evals are run by an **agent harness** (a Claude agent loading skills), not a pure
+shell script. `cases.yaml` is the fixture; this file is the procedure. Two things are
+measured: **triggering** (does the right skill fire?) and **capability** (does the skill
+make the answer better?).
+
+## 1. Triggering
+
+Goal: the `go` skill fires on `should_trigger` prompts and stays silent on
+`should_not_trigger` near-misses.
+
+Setup:
+- Load the **full skill catalog descriptions** (the routing layer sees every sibling:
+  fastapi, nextjs, go, postgresdb, flutter, design, marketing, presentations,
+  course-storytelling, building-agents, secure-coding, deployment, harness, init).
+- For each prompt, start a fresh agent session (no prior context bleed).
+
+Procedure:
+- Feed each `should_trigger.prompt`; record whether the agent invokes the `go` skill.
+- Feed each `should_not_trigger.prompt`; record which skill (if any) it invokes, and
+  confirm it matches the stated `route_to` (or `none`).
+- Run **3–5 trials per prompt** (LLM routing is non-deterministic); a prompt passes if it
+  fires correctly in the **majority** of trials.
+
+Pass bar:
+- **≥90% trigger accuracy** across all prompts (should_trigger fires AND should_not_trigger
+  does not fire `go`).
+- A `should_not_trigger` that routes to the *wrong* sibling but still avoids `go` is a
+  partial pass — log it; routing precision matters for the catalog.
+
+## 2. Capability
+
+Goal: the skill **measurably improves** the answer, not just decorates it.
+
+Procedure for each `capability.scenario`:
+1. **Without** the skill: run the scenario with the skill body unavailable. Grade the
+   answer against `must_include`.
+2. **With** the skill: run the same scenario with `go/SKILL.md` (and references) loaded.
+   Grade again against `must_include`.
+3. Score = fraction of `must_include` points present and correct. Run 3 trials per
+   condition and average.
+
+Pass bar:
+- **With** the skill: **≥80%** of `must_include` points covered.
+- The with-skill score must **beat** the without-skill score by a clear margin (the skill
+  is earning its place). If a baseline model already hits the rubric without the skill,
+  the rubric is too easy — tighten it.
+
+## Notes
+
+- Grading is rubric-based and partly judgment (e.g. "no string-matching of error
+  messages"); a human or a grader-agent reads each point against the output.
+- Keep `cases.yaml` faithful to `SKILL.md`'s "When to use / When NOT to use" — when the
+  skill's scope changes, update the cases in the same change.
+- These evals do not run in CI as-is; they are a reproducible manual/agent procedure.

package/skills/go/evals/cases.yaml

@@ -0,0 +1,55 @@
+skill: go
+
+should_trigger:
+  - prompt: "Write a Go HTTP service that exposes GET /users/{id} backed by Postgres, with graceful shutdown."
+    why: "Authoring a Go net/http service with 1.22 routing and shutdown is the skill's core use case."
+  - prompt: "Is this idiomatic? func NewStore(db *sql.DB) Store { return &store{db} } — should the constructor return the interface?"
+    why: "Idiom review (accept-interfaces/return-structs, consumer-side interfaces) is explicitly owned here, even without naming a tool."
+  - prompt: "My background worker keeps running after the request is cancelled and the process never exits cleanly. How do I fix it?"
+    why: "Goroutine-leak / context-plumbing debugging is a named trigger; the user never says 'Go' but the symptom is a classic Go leak this skill diagnoses."
+  - prompt: "Add table-driven tests with subtests for this parser and make sure CI catches data races."
+    why: "Table-driven tests + -race in CI is the skill's testing contract."
+  - prompt: "Review this code for problems before I ship it: it does fmt.Sprintf the id straight into a SELECT and has no http.Server timeouts."
+    why: "Go-specific security controls (SQL parametrization, server timeouts) are embedded here; this is a review-this-Go-code trigger."
+  - prompt: "How should I wrap and classify errors across my repository, service, and handler layers so I return the right HTTP status?"
+    why: "Go error wrapping with %w and errors.Is/As plus the 3-layer status mapping is canonically owned by this skill."
+  - prompt: "I have 5000 IDs to fetch from an API concurrently but I'm hammering it — how do I cap in-flight goroutines and cancel the rest on first failure?"
+    why: "Bounded concurrency with errgroup (SetLimit + derived ctx cancellation) is a core concurrency pattern here; user describes the problem without naming errgroup."
+
+should_not_trigger:
+  - prompt: "Do a threat model and OWASP-style authz review of my multi-tenant app's permission boundaries."
+    route_to: "secure-coding"
+    why: "Language-agnostic threat modeling and authz/abuse review is explicitly delegated to secure-coding; only Go-specific controls stay here."
+  - prompt: "Write a multi-stage Dockerfile and a GitHub Actions CI pipeline to build and deploy my service to Hetzner."
+    route_to: "deployment"
+    why: "Containerfile / CI / shipping is delegated to deployment; this skill ships only a Docker note plus ldflags."
+  - prompt: "Optimize this PostgreSQL query and design the indexes for a users table with a composite lookup."
+    route_to: "postgresdb"
+    why: "Pure SQL query/index design is a database concern; the Go skill only covers parametrization from the Go side, not schema/index tuning."
+  - prompt: "Build a FastAPI endpoint with Pydantic validation and async SQLAlchemy."
+    route_to: "fastapi"
+    why: "Python/FastAPI service work belongs to the fastapi skill, not the Go skill."
+  - prompt: "Record our team's chosen Go router, error conventions, and timeout defaults in the project wiki and index them from CLAUDE.md."
+    route_to: "harness"
+    why: "Authoring/indexing the 02-DOCS workspace wiki is the harness skill's job; the Go skill only writes its own stack article when that layer already exists."
+  - prompt: "Set up a Next.js App Router page that streams server components and calls our API."
+    route_to: "nextjs"
+    why: "Frontend/Next.js work is unrelated to Go services and routes to nextjs."
+
+capability:
+  - scenario: "Implement a Go HTTP endpoint GET /users/{id} that loads a user from Postgres and returns 404 when the user is missing, 500 on unexpected errors."
+    must_include:
+      - "Uses Go 1.22 routed mux pattern (mux.HandleFunc(\"GET /users/{id}\", h)) and r.PathValue(\"id\") instead of a manual router or path parsing"
+      - "Repository translates sql.ErrNoRows into a domain sentinel via fmt.Errorf(\"...: %w\", ErrNotFound), preserving the wrap chain"
+      - "Handler classifies with errors.Is(err, ErrNotFound) -> http.StatusNotFound and a default branch -> http.StatusInternalServerError (no string-matching of messages)"
+      - "Parametrizes the SQL query with $1 (no fmt.Sprintf string interpolation into the query)"
+      - "Logs only the unexpected error with slog (e.g. slog.Error) rather than leaking internal errors to the client body"
+      - "Dependencies injected via constructor (handler holds a service/store), no package-level mutable db/logger globals"
+  - scenario: "Wire up main() for the service: configure the http.Server, structured logging, and shutdown."
+    must_include:
+      - "Sets all four http.Server timeouts (ReadHeaderTimeout, ReadTimeout, WriteTimeout, IdleTimeout) as a Slowloris/DoS control"
+      - "Graceful shutdown using signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM) and srv.Shutdown(shutdownCtx) on <-ctx.Done()"
+      - "Configures log/slog JSON handler and calls slog.SetDefault, with level read from env"
+      - "Wires layers with constructor injection outermost-inward (repo := repository.New(db); svc := service.New(repo); h := handler.New(svc))"
+      - "Mentions running govulncheck ./... and go test -race before shipping"
+      - "context.Context threaded as the first parameter, never stored in a struct or passed as nil"