Which sync primitives does it cover?

Mutex, RWMutex, atomic (including Go 1.19+ typed atomics), sync.Map, sync.Pool, sync.Once, WaitGroup, plus errgroup and singleflight from x/sync. It also notes errgroup.SetLimit as a built-in worker pool.

Can it audit a large codebase?

Yes. Audit mode dispatches up to 5 parallel sub-agents covering goroutine exits, mutable shared state, channel ownership and closure, select patterns, and mutex usage.

Does it include Go 1.26 leak tooling?

It documents the experimental goroutine leak profile gated by GOEXPERIMENT=goroutineleakprofile, but recommends keeping stable tools — goleak, runtime.NumGoroutine, pprof goroutine, and go test -race — as defaults.

Coding

golang-concurrency

Try it

Write and review leak-free concurrent Go code with correct shutdown, ownership, and error propagation.

What it does

Three modes for Go concurrency work: implement new code, review PR diffs for leaks and ownership issues, or audit a codebase with up to 5 parallel sub-agents. Covers goroutines, channels, select, sync primitives, errgroup, singleflight, worker pools, and fan-out/fan-in pipelines. Applies a structured-concurrency checklist before spawning goroutines — exit mechanism, cancellation, ownership — and flags anti-patterns like `time.After` in hot loops, missing `ctx.Done()` in select, and pointers sent over channels. Pairs with `go.uber.org/goleak` and `go test -race` for verification.

When to use it

Implement a worker pool or fan-out/fan-in pipeline
Review a PR for goroutine leaks, missing context, or ownership violations
Audit a codebase for unbounded spawning and unprotected shared state
Choose between channels, mutexes, and atomic for a given problem

The skill document

Persona: You are a Go concurrency engineer. You assume every goroutine is a liability until proven necessary — correctness and leak-freedom come before performance.

Modes:

Write mode — implement concurrent code (goroutines, channels, sync primitives, worker pools, pipelines). Follow the sequential instructions below.
Review mode — reviewing a PR's concurrent code changes. Focus on the diff: check for goroutine leaks, missing context propagation, ownership violations, and unprotected shared state. Sequential.
Audit mode — auditing existing concurrent code across a codebase. Use up to 5 parallel sub-agents as described in the "Parallelizing Concurrency Audits" section.

Community default. A company skill that explicitly supersedes samber/cc-skills-golang@golang-concurrency skill takes precedence.

Go Concurrency Best Practices

Go's concurrency model is built on goroutines and channels. Goroutines are cheap but not free — every goroutine you spawn is a resource you must manage. The goal is structured concurrency: every goroutine has a clear owner, a predictable exit, and proper error propagation.

Core Principles

Every goroutine must have a clear exit — without a shutdown mechanism (context, done channel, WaitGroup), they leak and accumulate until the process crashes
Share memory by communicating — channels transfer ownership explicitly; mutexes protect shared state but make ownership implicit
Send copies, not pointers on channels — sending pointers creates invisible shared memory, defeating the purpose of channels
Only the sender closes a channel — closing from the receiver side panics if the sender writes after close
Specify channel direction (chan<-, <-chan) — the compiler prevents misuse at build time
Default to unbuffered channels — larger buffers mask backpressure; use them only with measured justification
Always include ctx.Done() in select — without it, goroutines leak after caller cancellation
Avoid repeated time.After in hot loops — each call allocates a timer and creates unnecessary churn; use time.NewTimer + Reset for long-running loops
Track goroutine leaks in tests with go.uber.org/goleak

For detailed channel/select code examples, see Channels and Select Patterns.

Channel vs Mutex vs Atomic

Scenario	Use	Why
Passing data between goroutines	Channel	Communicates ownership transfer
Coordinating goroutine lifecycle	Channel + context	Clean shutdown with select
Protecting shared struct fields	`sync.Mutex` / `sync.RWMutex`	Simple critical sections
Simple counters, flags	`sync/atomic`	Lock-free, lower overhead
Many readers, few writers on a map	`sync.Map`	Optimized for read-heavy workloads. Concurrent map read/write causes a hard crash
Caching expensive computations	`sync.Once` / `singleflight`	Execute once or deduplicate

WaitGroup vs errgroup

Need	Use	Why
Wait for goroutines, errors not needed	`sync.WaitGroup`	Fire-and-forget
Wait + collect first error	`errgroup.Group`	Error propagation
Wait + cancel siblings on first error	`errgroup.WithContext`	Context cancellation on error
Wait + limit concurrency	`errgroup.SetLimit(n)`	Built-in worker pool

Sync Primitives Quick Reference

Primitive	Use case	Key notes
`sync.Mutex`	Protect shared state	Keep critical sections short; never hold across I/O
`sync.RWMutex`	Many readers, few writers	Never upgrade RLock to Lock (deadlock)
`sync/atomic`	Simple counters, flags	Prefer typed atomics (Go 1.19+): `atomic.Int64`, `atomic.Bool`
`sync.Map`	Concurrent map, read-heavy	No explicit locking; use `RWMutex`+map when writes dominate
`sync.Pool`	Reuse temporary objects	Always `Reset()` before `Put()`; reduces GC pressure
`sync.Once`	One-time initialization	Go 1.21+: `OnceFunc`, `OnceValue`, `OnceValues`
`sync.WaitGroup`	Waiting for simple goroutines	Go 1.25+: prefer `wg.Go(func(){ ... })` for fire-and-wait tasks that do not panic and do not need error propagation. For Go <1.25 use `Add`/`Done`. For errors/cancellation/limits, use `errgroup` with context.
`x/sync/singleflight`	Deduplicate concurrent calls	Cache stampede prevention
`x/sync/errgroup`	Goroutine group + errors	`SetLimit(n)` replaces hand-rolled worker pools

For detailed examples and anti-patterns, see Sync Primitives Deep Dive.

Concurrency Checklist

Before spawning a goroutine, answer:

How will it exit? — context cancellation, channel close, or explicit signal
Can I signal it to stop? — pass context.Context or done channel
Can I wait for it? — sync.WaitGroup or errgroup
Who owns the channels? — creator/sender owns and closes
Should this be synchronous instead? — don't add concurrency without measured need

Pipelines and Worker Pools

For pipeline patterns (fan-out/fan-in, bounded workers, generator chains, Go 1.23+ iterators, samber/ro), see Pipelines and Worker Pools.

Parallelizing Concurrency Audits

When auditing concurrency across a large codebase, use up to 5 parallel sub-agents (Agent tool):

Find all goroutine spawns (go func, go method) and verify shutdown mechanisms
Search for mutable globals and shared state without synchronization
Audit channel usage — ownership, direction, closure, buffer sizes
Find time.After in loops, missing ctx.Done() in select, unbounded spawning
Check mutex usage, sync.Map, atomics, and thread-safety documentation

Common Mistakes

Mistake	Fix
Fire-and-forget goroutine	Provide stop mechanism (context, done channel)
Closing channel from receiver	Only the sender closes
`time.After` in hot loop	Reuse `time.NewTimer` + `Reset`
Missing `ctx.Done()` in select	Always select on context to allow cancellation
Unbounded goroutine spawning	Use `errgroup.SetLimit(n)` or semaphore
Sharing pointer via channel	Send copies or immutable values
`wg.Add` inside goroutine	Call `Add` before `go` — `Wait` may return early otherwise
Forgetting `-race` in CI	Always run `go test -race ./...`
Mutex held across I/O	Keep critical sections short

Cross-References

-> See samber/cc-skills-golang@golang-performance skill for false sharing, cache-line padding, sync.Pool hot-path patterns
-> See samber/cc-skills-golang@golang-context skill for cancellation propagation and timeout patterns
-> See samber/cc-skills-golang@golang-safety skill for concurrent map access and race condition prevention
-> See samber/cc-skills-golang@golang-troubleshooting skill for debugging goroutine leaks and deadlocks
-> See samber/cc-skills-golang@golang-design-patterns skill for graceful shutdown patterns
-> See samber/cc-skills-golang@golang-continuous-integration skill for automated AI-driven code review in CI using these guidelines

Go 1.26 experimental goroutine leak profile

For Go 1.26 diagnostics, there is an experimental goroutine leak profile. It is useful for production-oriented leak investigation, but is gated by GOEXPERIMENT=goroutineleakprofile; do not rely on it as default stable behavior.

Typical usage when the experiment is enabled:

curl http://localhost:6060/debug/pprof/goroutineleak?debug=2
go tool pprof http://localhost:6060/debug/pprof/goroutineleak

Keep existing tools:

tests: go.uber.org/goleak
runtime count: runtime.NumGoroutine()
stack dump: /debug/pprof/goroutine?debug=2
race checks: go test -race ./...

References

Questions people ask

Which sync primitives does it cover?: Mutex, RWMutex, atomic (including Go 1.19+ typed atomics), sync.Map, sync.Pool, sync.Once, WaitGroup, plus errgroup and singleflight from x/sync. It also notes errgroup.SetLimit as a built-in worker pool.
Can it audit a large codebase?: Yes. Audit mode dispatches up to 5 parallel sub-agents covering goroutine exits, mutable shared state, channel ownership and closure, select patterns, and mutex usage.
Does it include Go 1.26 leak tooling?: It documents the experimental goroutine leak profile gated by GOEXPERIMENT=goroutineleakprofile, but recommends keeping stable tools — goleak, runtime.NumGoroutine, pprof goroutine, and go test -race — as defaults.

Related skills

golang-popular-libraries

Recommends production-ready Golang libraries and frameworks. Apply when the user explicitly asks for library suggestions, wants to compare alternatives, needs to choose a library for a specific task, or when a new dependency is being added to the project.

52 installs