go

name	go
description	This skill should be used when the user works with Go files (.go), asks about "error handling", "interfaces", "goroutines", "channels", "packages", or discusses Go idioms and concurrency. Provides patterns for error handling, interface design, concurrency, and package organization.
user-invocable	false
allowed-tools	Read, Grep, Glob
activation	{"file-patterns":["**/*.go"],"exclude":["vendor/**"]}

Go Patterns

Reference for Go-specific patterns, idioms, and best practices. Full bibliography: references/sources.md.

Iron Law

ERRORS ARE VALUES [5][7]

Never ignore errors. if err != nil is correctness, not boilerplate. Every error return must be checked, wrapped with context, or explicitly documented as intentionally ignored with _ = fn(). "Errors are values. Values can be programmed." — Rob Pike [5]

When This Skill Activates

Working with Go codebases — error handling, interfaces, goroutines, channels, packages.

---

Error Handling [5][6]

// BAD: return err  — caller loses context
// GOOD: return fmt.Errorf("reading config %s: %w", path, err)

var ErrNotFound = errors.New("not found")

func FindUser(id string) (*User, error) {
    u, err := db.Get(id)
    if err != nil {
        return nil, fmt.Errorf("finding user %s: %w", id, err)
    }
    if u == nil { return nil, ErrNotFound }
    return u, nil
}
// Caller: if errors.Is(err, ErrNotFound) { ... }

---

Interface Design [7][14]

// "The bigger the interface, the weaker the abstraction" — Rob Pike [7]
// BAD: func NewService(repo *PostgresRepo) *Service
// GOOD: func NewService(repo Repository) *Service — accept interfaces [14]

// Small interfaces compose cleanly [1]
type Reader interface { Read(p []byte) (n int, err error) }
type Writer interface { Write(p []byte) (n int, err error) }
type ReadWriter interface { Reader; Writer }

---

Concurrency [9][10][13]

CSP (Hoare [9]): "Do not communicate by sharing memory; share memory by communicating." [10]

// Context cancellation with errgroup [16][22]
func Process(ctx context.Context, items []Item) error {
    g, ctx := errgroup.WithContext(ctx)
    for _, item := range items {
        g.Go(func() error { return processItem(ctx, item) })
    }
    return g.Wait()
}

// Channel direction prevents misuse at compile time [1][8]
func producer(ch chan<- int) { ch <- 42 }
func consumer(ch <-chan int) { v := <-ch; _ = v }

---

Package Design [15][17]

// BAD: models/, controllers/, services/
// GOOD: user/, order/, payment/  — organize by domain [15]

func (s *Service) validate(u *User) error { ... }   // unexported — internal only
func (s *Service) CreateUser(ctx context.Context, req CreateUserReq) (*User, error) { ... }

---

Zero Values [1]

var mu sync.Mutex; var buf bytes.Buffer  // Ready to use — no init needed

type Config struct {
    Timeout time.Duration // zero = no timeout
    Retries int           // zero = no retries
}

---

Anti-Patterns

Pattern	Violation	Source
Ignoring error	val, _ := fn()	[5][2]
Naked return	return in named returns	[2][4]
init() abuse	Complex init() with side effects	[1][12]
Interface pollution	Interface defined before use	[14][7]
Goroutine leak	go fn() without lifecycle	[13][16]
Panic in library	panic(err) in non-main code	[1][4]

---

Extended References

• references/sources.md — Full bibliography (25 sources)
• references/violations.md — Violations with citations [5][6][7][12][13]
• references/patterns.md — Extended patterns with citations [1][3][11][18][19]
• references/detection.md — Grep patterns for automated detection
• references/concurrency.md — CSP-grounded concurrency patterns [9][10][13][22]

---

Checklist

• All errors checked or explicitly ignored with _ = [5]
• Errors wrapped with fmt.Errorf("context: %w", err) [6]
• Interfaces defined at consumer, not producer [14]
• Interfaces kept small (1-3 methods) [7]
• Context as first parameter [16]
• Goroutines have clear lifecycle/cancellation [13]
• Channel direction specified in signatures [8]
• Packages organized by domain, not by type [15]
• No init() with side effects [1]
• No panic or log.Fatal in library code [4]