Go

User preferences live in ~/Clawic/data/go/config.yaml (see Configuration); nothing else is stored on the user's machine. If you have data at an old location (~/go/ or ~/clawic/go/), move it to ~/Clawic/data/go/. Note that ~/go/ may also be the user's GOPATH — never write skill data there, and never delete it.

When To Use

• Writing or reviewing Go — scan Core Rules and Output Gates before committing
• Any panic, fatal error:, or race warning whose cause is not obvious in ten seconds
• Hangs, goroutine growth, rising RSS, and CPU that appears without traffic
• Concurrency design: channels vs mutexes, worker pools, cancellation, fan-in/fan-out
• Toolchain and dependency work: modules, versions, build tags, cross-compilation, containers
• API and package design decisions: interfaces, generics, error contracts, layout
• Not for Kubernetes operators, gRPC service design, or web-framework internals — those live in their own skills

Quick Reference

Each file above is one sub-job and is self-contained: read SKILL.md by default, open exactly one guide when the situation matches.

Core Rules

1. No goroutine without a written exit path. A closed channel, a ctx.Done() case, or a loop with a bound — decided before the go keyword is typed. A handler that starts one un-cancellable goroutine per request at 1,000 rps leaks 3.6M goroutines an hour; at ~2 KB of initial stack each that is the whole heap (concurrency.md).
2. Check the error at the call site; wrap with %w when you add context. fmt.Errorf("load config %s: %w", path, err). %v flattens the chain and silently breaks errors.Is/errors.As for every caller above you. Ignoring an error needs _ = plus a written reason (errors.md).
3. An interface is nil only when its type word AND its value word are nil. var e *MyErr = nil; var err error = e → err != nil is true and every if err != nil above fires. Declare the return as error and return the literal nil, never a typed nil (interfaces.md).
4. ctx context.Context is the first parameter of every call that can block, and every WithCancel/WithTimeout is followed by defer cancel(). Skipping cancel() leaks the timer and the child context until the parent finishes — go vet's lostcancel catches the common shape (context.md).
5. defer fires at function return, not at end of block. for ... { rows, _ := db.Query(...); defer rows.Close() } holds every result set until the function returns and exhausts the pool. Move the body into its own function, or call Close() explicitly at the end of the iteration (io.md).
6. Any variable touched by two goroutines needs a mutex, a channel, or sync/atomic. "It is just an int" is the most common data race in Go. go test -race proves nothing about code paths it did not execute, so run it on the suite, not on one test (debugging.md).
7. Reslicing shares the array; appending may or may not copy. b := a[1:3]; append(b, x) overwrites a[3] whenever len(b) < cap(b), and cap(a[i:j]) == cap(a) - i. Force a copy with the three-index form a[1:3:3], which sets cap to len so the next append must reallocate (collections.md).
8. Zero values are usable except for maps and channels. var s []int appends fine and marshals as null; var m map[string]int reads fine and panics on write; var ch chan int blocks forever on both send and receive. make maps and channels; leave slices, sync.Mutex, bytes.Buffer, and strings.Builder at zero.
9. Loop-variable capture is gated on the go line in go.mod, not on the toolchain. With go >=1.22 the variable is per-iteration, so for _, v := range xs { go f(v) } is correct; below that line every goroutine sees the last element, even when built with a new compiler. Check the go directive before trusting the pattern (versions.md).

Version Floors

The floors that shape everyday Go. Individual guides carry more floors inline in this same go >=X.Y form, next to the instruction each one gates. Release policy, upgrade procedure, and removals: versions.md.

Panics And Fatal Errors

panic unwinds and runs defers, so recover() can catch it. fatal error: does not: the runtime kills the process immediately and no defer, recover, or handler sees it. Knowing which one you got halves the search.

Output Gates

Before delivering Go code, check:

• Every go statement has a stated exit path, and every WithCancel/WithTimeout has defer cancel()
• Every error is checked; context added with %w; every discarded error has _ = and a written reason
• ctx is the first parameter of every exported call that blocks, and every network, database, lock, and subprocess call has a deadline
• No exported function returns a concrete error type as error; no typed nil escapes as an interface
• Every acquired resource closes on every path, including the error paths, and Close() errors on writers are checked
• go vet is clean and go test -race ./... ran at least once against the changed packages
• Syntax and stdlib stay within min_go, and the go directive in go.mod actually allows what you emitted
• Nothing untrusted reaches text/template for HTML, a concatenated SQL string, os/exec with a shell, or a path join without containment; no math/rand for anything secret

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/go/config.yaml. Never interview the user — record a preference the moment it is stated.

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Tooling: linter set (go vet only, golangci-lint standard or strict), mock generator, migration tool, task runner, go work vs one module per repo — affects every emitted config block and command (idioms.md)
• Conventions: receiver names and pointer-vs-value policy, error message phrasing, table-test naming, comment and doc style, struct-tag conventions — affects generated code and review comments
• Platform: deployment target (container, serverless, CLI distribution, embedded), CPU architecture, private module proxy, CI provider — affects deployment.md and modules.md guidance
• Safety posture: how aggressively to flag missing timeouts, unchecked errors, panic in library code, unbounded goroutines, and unpinned dependencies — affects security.md and review depth
• Dependencies: stdlib-only constraints, banned or mandated libraries (pkg/errors vs stdlib, sqlx vs database/sql, ORM policy), tolerance for new transitive dependencies — affects every recommendation
• Output format: whole file vs minimal diff, how much explanation, whether tests and benchmarks accompany every change — affects the shape of the answer, never the correctness rules
• Work order: which gates run before a change is proposed rather than after — go vet and -race green first, a benchmark before any optimization, a plan approved before restructuring packages — affects the sequence of every task, never the correctness rules
• Cadence: beyond upgrade_cadence — the day and batch size for go get -u runs, whether a new Go release is adopted in its first weeks or after .1, how often govulncheck and go mod tidy run in CI, and the review interval for pinned replace directives — affects versions.md and modules.md, never the correctness rules
• Thresholds and sizing: the numbers a team standardises beyond default_timeout — SetMaxOpenConns/SetMaxIdleConns against the database's own connection cap divided by instance count, GOMEMLIMIT headroom (default ~90% of the container limit), benchmark -count (default 10) and the benchstat delta that counts as a win, http.MaxBytesReader body cap (default 1 MiB), worker-pool width — affects which value gets emitted, while Safety posture governs whether a missing one is flagged

Traps

Where Experts Disagree

• Channels vs mutexes. "Share memory by communicating" is the slogan; the Go team's own guidance is that a mutex around shared state is often simpler and faster. Boundary: channels when ownership of a value moves between goroutines or you need cancellation and fan-out; a sync.Mutex when several goroutines read and write one struct in place. A channel used purely as a lock is a slower lock (concurrency.md).
• Project layout. The golang-standards/project-layout tree (pkg/, api/, build/) is community folklore, not a Go team standard, and the standard library itself is flat. Boundary: a single binary starts flat and grows internal/ when a package must not be imported outside; multi-binary repos earn cmd/. Ceremony before the second binary exists is cost without benefit (idioms.md).
• How opaque errors should be. One school wraps at every hop so callers can errors.Is anything; the other treats error identity as API surface and exports only a few sentinels, hiding the rest behind behavioral checks. Boundary: within one module, wrap freely; across a published API, every exported sentinel and error type is a compatibility promise you cannot retract (errors.md).
• Generics vs interfaces. Type parameters remove any from container and algorithm code, but Go compiles them with GC-shape stenciling: all pointer-shaped instantiations share one body plus a dictionary, so generic code over pointers can call indirectly where an interface would too. Boundary: identical logic across types that share no methods → type parameters; behavior that differs per type → interface (generics.md).

Related Skills

More Clawic skills, get them at https://clawic.com/skills/go (install if the user confirms):

• concurrency — language-agnostic memory model: happens-before, atomics, lock-free tradeoffs
• debugging — hypothesis-driven fault isolation; the Go-specific version of that job is this skill's debugging.md
• profiling — choosing the right clock and reading flame graphs, whatever the language
• docker — building and running the container the Go binary ships in
• api-design — the HTTP contract itself, above the handler code

Feedback

• If useful, star it: https://clawic.com/skills/go
• Latest version: https://clawic.com/skills/go

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/go.