Golang Concurrency

Samuel BertheCommunityCreated by samberDistributed by Samuel Berthe

Skill
Guidelines
Software development
MIT
Low risk

From the author

Golang concurrency design — goroutine lifecycle and leak prevention, channels and `select`, channel ownership and direction, `sync.Mutex`/`RWMutex`/`sync.Map`/`sync.Once`/atomics, `errgroup`, `singleflight`, worker pools, and fan-out/fan-in pipelines. Use when writing or reviewing concurrent Go code, when choosing between channels and mutexes, when protecting a shared map or counter, or when a goroutine has no clear exit. Not for defensive coding unrelated to concurrency such as nil panics, slice aliasing, or numeric overflow (→ See `samber/cc-skills-golang@golang-safety` skill), and not for debugging a specific hung, crashing, or racing program after the fact (→ See `samber/cc-skills-golang@golang-troubleshooting` skill).

— the description by samber

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a comprehensive framework for designing and auditing concurrent Go applications. It emphasizes structured concurrency, focusing on goroutine lifecycle management, leak prevention, and the correct application of synchronization primitives like channels, mutexes, and atomics. The skill includes specific patterns for worker pools, fan-out/fan-in pipelines, and error propagation using errgroup, while providing a systematic approach to auditing codebases for concurrency issues.

What it does

Provides design patterns for goroutine lifecycle management and clean shutdown.
Offers guidance on choosing between channels, mutexes, atomics, and sync primitives.
Defines best practices for implementing worker pools and pipeline architectures.
Includes a structured checklist for reviewing concurrent code and identifying potential leaks.
Supports multi-agent orchestration for auditing concurrency across large codebases.
References standard synchronization tools like errgroup, singleflight, and sync.Map.

When to use it

When writing new concurrent Go code that requires robust lifecycle management.
When reviewing pull requests to identify goroutine leaks or ownership violations.
When auditing an existing codebase for unprotected shared state or synchronization errors.
When determining the appropriate concurrency primitive for a specific synchronization task.

Advantages

Promotes structured concurrency to prevent goroutine leaks and deadlocks.
Standardizes the use of synchronization primitives across development teams.
Facilitates systematic auditing of complex concurrent systems.
Provides clear, actionable patterns for common concurrency challenges.

Usage examples

“Review this PR for goroutine leaks and synchronization issues.”: The agent analyzes the diff, checking for missing context propagation, improper channel closure, and unprotected shared state.
“Help me implement a worker pool for processing tasks.”: The agent provides a pattern using errgroup.SetLimit to manage bounded concurrency and ensure clean error handling.
“Audit the codebase for potential concurrency bugs.”: The agent orchestrates multiple sub-agents to scan for mutable globals, improper channel usage, and missing context cancellation.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/samber/golang-concurrency/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip golang-concurrency.zip -d .agents/skills

Documentation by samber

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

Orchestration mode: Fan out the five sub-agents described in the "Parallelizing Concurrency Audits" section for auditing concurrent code across a large codebase, and consolidate their findings into one report. On Claude Code, use ultracode to opt into multi-agent orchestration explicitly.

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:

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

Goroutine leak profile

The goroutine leak profile (experimental behind GOEXPERIMENT=goroutineleakprofile in Go 1.26) is generally available in runtime/pprof since Go 1.27 — no build flag required. It is a useful production-oriented leak signal alongside the existing tools below.

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

Files

ATTRIBUTION.mdAdded by AutoGineer911 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md9.3 KiB
evals/evals.json16.1 KiB
references/channels-and-select.md4.3 KiB
references/pipelines.md7.2 KiB
references/sync-primitives.md8.6 KiB

references/pipelines.md

Pipelines and Worker Pools

Pipeline Pattern
Fan-Out / Fan-In
Worker Pool with errgroup
Bounded Concurrency with Semaphore
Pipeline Alternatives
- Go 1.23+ Iterators (range-over-func)
- samber/ro
Goroutine Leak Detection
Common Pipeline Mistakes

Pipeline Pattern

A pipeline is a series of stages connected by channels, where each stage is a goroutine (or group of goroutines) that:

Receives values from an upstream channel
Processes each value
Sends results to a downstream channel

// Stage 1: Generate integers
func generate(ctx context.Context, nums ...int) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for _, n := range nums {
            select {
            case out <- n:
            case <-ctx.Done():
                return
            }
        }
    }()
    return out
}

// Stage 2: Square each integer
func square(ctx context.Context, in <-chan int) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for n := range in {
            select {
            case out <- n * n:
            case <-ctx.Done():
                return
            }
        }
    }()
    return out
}

// Usage
func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    ch := generate(ctx, 2, 3, 4)
    results := square(ctx, ch)

    for v := range results {
        fmt.Println(v) // 4, 9, 16
    }
}

Key rules for pipelines:

Pipeline stages MUST accept and respect context cancellation — every stage must select on ctx.Done() to avoid goroutine leaks on early cancellation
The producer (first stage) closes its output channel; each subsequent stage closes its own output
NEVER create unbounded goroutines in pipeline stages
Use unbuffered channels unless you have measured throughput needs

Fan-Out / Fan-In

Fan-out: multiple goroutines read from the same channel to parallelize CPU-bound work. Fan-in: multiple channels are merged into a single output channel.

// Fan-out: N workers reading from the same input channel
func fanOut(ctx context.Context, in <-chan Task, workers int) <-chan Result {
    out := make(chan Result)
    var wg sync.WaitGroup

    for i := 0; i < workers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for {
                select {
                case task, ok := <-in:
                    if !ok {
                        return
                    }
                    select {
                    case out <- process(ctx, task):
                    case <-ctx.Done():
                        return
                    }
                case <-ctx.Done():
                    return
                }
            }
        }()
    }

    go func() {
        wg.Wait()
        close(out)
    }()
    return out
}

// Fan-in: merge multiple channels into one
func fanIn(ctx context.Context, channels ...<-chan Result) <-chan Result {
    out := make(chan Result)
    var wg sync.WaitGroup

    for _, ch := range channels {
        wg.Add(1)
        go func(c <-chan Result) {
            defer wg.Done()
            for v := range c {
                select {
                case out <- v:
                case <-ctx.Done():
                    return
                }
            }
        }(ch)
    }

    go func() {
        wg.Wait()
        close(out)
    }()
    return out
}

Worker Pool with errgroup

Fan-out workers SHOULD use errgroup.SetLimit for bounded concurrency. For most use cases, errgroup.SetLimit replaces hand-rolled worker pools:

func processAll(ctx context.Context, tasks []Task) error {
    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(10) // max 10 concurrent workers

    for _, task := range tasks {
        g.Go(func() error {
            return process(ctx, task)
        })
    }
    return g.Wait()
}

Use a hand-rolled worker pool only when you need:

Per-worker state (connections, buffers)
Custom backpressure or priority scheduling
Graceful draining with in-flight task completion

Bounded Concurrency with Semaphore

When you need fine-grained concurrency control without errgroup:

func processAll(ctx context.Context, items []Item) error {
    sem := make(chan struct{}, 10) // semaphore of 10
    var wg sync.WaitGroup

    for _, item := range items {
        wg.Add(1)
        sem <- struct{}{} // acquire
        go func(item Item) {
            defer wg.Done()
            defer func() { <-sem }() // release
            process(ctx, item)
        }(item)
    }
    wg.Wait()
    return nil
}

Prefer errgroup.SetLimit over this pattern when error propagation is needed.

Pipeline Alternatives

Go 1.23+ Iterators (range-over-func)

For in-process data transformations that do not need concurrency, iterators avoid the overhead of goroutines and channels:

func Filter[T any](seq iter.Seq[T], pred func(T) bool) iter.Seq[T] {
    return func(yield func(T) bool) {
        for v := range seq {
            if pred(v) {
                if !yield(v) {
                    return
                }
            }
        }
    }
}

func Map[T, U any](seq iter.Seq[T], f func(T) U) iter.Seq[U] {
    return func(yield func(U) bool) {
        for v := range seq {
            if !yield(f(v)) {
                return
            }
        }
    }
}

Use iterators when:

Processing is CPU-bound and does not benefit from parallelism
You want lazy evaluation without goroutine overhead
The data source is already sequential (slice, database cursor)

Use goroutine+channel pipelines when:

Stages involve I/O (network, disk) that benefits from concurrency
You need true parallelism across CPU cores
Stages have different throughput characteristics

samber/ro

samber/ro provides a fluent, type-safe pipeline API for read-only collections:

import "github.com/samber/ro"

emails, _ := ro.Collect( // ignore error
    ro.Pipe(
        ro.FromSlice(users),
        ro.Filter(func(u User) bool { return u.Active }),
        ro.Map(func(u User) string { return u.Email }),
    ),
)

Use samber/ro for sequential data transformations that benefit from a fluent API. It might also support parallel processing if needed.

Goroutine Leak Detection

Goroutine leaks SHOULD be detected with goleak in tests. Use go.uber.org/goleak in TestMain to catch leaked goroutines across all tests:

func TestMain(m *testing.M) {
    goleak.VerifyTestMain(m)
}

Common Pipeline Mistakes

Mistake	Fix
Missing `ctx.Done()` in pipeline stage	Always select on context to allow cancellation
Not closing output channel	Producer must `defer close(out)`
Unbounded goroutine spawning	Use `errgroup.SetLimit` or a semaphore
Sending mutable data through channel	Send copies or immutable values
Blocking send without select	Wrap channel sends in select with `ctx.Done()`

→ See samber/cc-skills-golang@golang-concurrency skill for sync primitives and channel patterns.

Requirements and compatibility

Written for: Claude Code, OpenAI Codex

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Claude Code frontmatter, Needs network access

The author says: Designed for Claude Code, Codex or similar harness, and for projects using Golang.

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

samber

Publisher

Samuel Berthe (Community)

Distributed by

Samuel Berthe

Source

samber/cc-skills-golang · skills/golang-concurrency · commit bb1d43d

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by samber or Samuel Berthe.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download golang-concurrency.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by samber

Go Concurrency Best Practices

Core Principles

Channel vs Mutex vs Atomic

WaitGroup vs errgroup

Sync Primitives Quick Reference

Concurrency Checklist

Pipelines and Worker Pools

Parallelizing Concurrency Audits

Common Mistakes

Cross-References

Goroutine leak profile

References

Files

references/pipelines.md

Pipelines and Worker Pools

Table of Contents

Pipeline Pattern

Fan-Out / Fan-In

Worker Pool with errgroup

Bounded Concurrency with Semaphore

Pipeline Alternatives

Go 1.23+ Iterators (range-over-func)

samber/ro

Goroutine Leak Detection

Common Pipeline Mistakes

Requirements and compatibility

Security

Attribution and licence

Related skills

Implement

Source Driven Development

Write Swift

Cardputer Buddy

Typescript Pro

Scala Pro

Download ZIP