go

name	go
description	Go development skill covering style, idioms, testing, concurrency, and distributed systems patterns. Use when writing, reviewing, or modifying Go code. Also use when the user asks about Go best practices, architecture decisions, or debugging Go-specific issues. Covers Go 1.22+ features including range-over-func, enhanced routing, generics, and testing/synctest.

Go

This skill contains opinionated guidance for writing production Go code. The rules here reflect deliberate choices — follow them even when they conflict with generic Go advice from other sources.

Core principles

• Clarity over cleverness. Code is read far more than it's written. Prefer the obvious approach.
• Concrete first, abstract later. Start with concrete types, plain functions, and simple loops. Introduce generics, iterators, or interfaces only when duplication or a clear design need forces it.
• Small interfaces, big structs. Interfaces should have 1-2 methods. Define them at the consumer, not the implementor.
• Errors are values. Handle them explicitly. Don't panic in library code. Wrap at boundaries, not at every return.
• Test the exported API. Unexported functions are implementation details. If the public behavior is correct, the internals are correct by definition.

References

Read these only when the task involves the relevant topic. Do not read all references upfront.

Style and idioms

File	Read when...
references/style/style.md	Writing any new Go code, reviewing naming, structuring packages, or deciding on function signatures. This is the most broadly applicable reference.

Testing

File	Read when...
references/testing/unit-testing.md	Writing or modifying *_test.go files, adding test coverage, or reviewing test structure.
references/modern-go/synctest.md	Testing code that uses goroutines, channels, timers, tickers, or context deadlines.

Modern Go features

File	Read when...
references/modern-go/error-handling-evolution.md	Creating error types, wrapping errors, using errors.Is/errors.As, or deciding between sentinel errors and custom types.
references/modern-go/generics.md	Writing or reviewing generic functions, type constraints, or deciding whether generics are warranted.
references/modern-go/iterators.md	Implementing custom iterators, using iter.Seq/iter.Seq2, replacing channel-based iteration, or composing lazy sequences.
references/modern-go/enhanced-http-routing.md	Writing HTTP handlers with net/http, registering routes with method matching or path wildcards.
references/modern-go/structured-logging.md	Adding logging with log/slog, choosing log levels, or structuring log output.

Distributed systems

File	Read when...
references/distributed-systems/retries-and-backoffs.md	Adding retry logic, exponential backoff, jitter, or using cenkalti/backoff.
references/distributed-systems/circuit-breakers.md	Protecting against cascading failures, wrapping external service calls with failsafe-go.
references/distributed-systems/timeouts-and-cancellation.md	Setting timeouts on outgoing calls, propagating context.Context, or debugging context cancellation issues.

Common combinations

Some tasks require multiple references. Read all that apply:

• Writing a new service client → style + timeouts + retries + circuit breakers + error handling
• Writing tests for concurrent code → unit testing + synctest
• Adding a new HTTP endpoint → style + enhanced HTTP routing + error handling
• Reviewing a PR → style + whichever topic-specific references match the changed code