Skill

Pass

Audit score 90

golang-concurrency

samber/cc-skills-golang

Design and audit Go concurrency: goroutines, channels, mutexes, worker pools, and leak prevention.

What is golang-concurrency?

A concurrency design guide for writing and reviewing Go concurrent code. Use when implementing goroutines and channels, choosing between sync primitives, protecting shared state, or auditing a codebase for goroutine leaks and ownership violations. Covers goroutine lifecycle, channel patterns, sync.Mutex/RWMutex/Map/Once, atomics, errgroup, singleflight, worker pools, and fan-out/fan-in pipelines.

Verify every goroutine has a clear exit and shutdown mechanism to prevent leaks
Choose between channels, mutexes, atomics, and sync.Map for your use case
Audit channel ownership, direction, closure, and buffer sizes
Detect missing context propagation and unprotected shared state in concurrent code
Implement worker pools, pipelines, and fan-out/fan-in patterns with errgroup and singleflight
Parallelize concurrency audits across large codebases using multi-agent orchestration

How to install golang-concurrency

npx skills add https://github.com/samber/cc-skills-golang --skill golang-concurrency

Prerequisites

Go toolchain installed (go binary required)
golangci-lint installed (optional, for linting concurrent code)
Familiarity with basic Go syntax and goroutines

Claude Code

Cursor

Windsurf

Cline

How to use golang-concurrency

1.Identify your concurrency need: passing data (channels), protecting state (mutex/atomic), or coordinating lifecycle (context/WaitGroup)
2.Apply the Core Principles checklist: verify goroutine exit, ownership, and context propagation
3.Use the Channel vs Mutex vs Atomic table to pick the right primitive for your scenario
4.For write mode: follow the sequential implementation steps; for review mode: focus on the diff for leaks and ownership; for audit mode: run parallel sub-agents across the codebase
5.Check your code against the Common Mistakes table and run tests with -race flag

Use cases

Good for

Writing a new concurrent service with goroutines and channels, ensuring leak-free design
Reviewing a PR that adds concurrent code, checking for ownership violations and missing context
Auditing an existing codebase for goroutine leaks, unprotected shared maps, and improper mutex usage
Choosing between sync.Mutex, sync.RWMutex, sync.Map, or atomics for protecting a counter or flag
Implementing a worker pool or pipeline to process tasks concurrently with bounded concurrency

Who it's for

Go backend engineers writing concurrent services
Code reviewers auditing concurrent Go changes
DevOps and platform teams maintaining large Go codebases
Anyone implementing goroutines, channels, or sync primitives in Go

golang-concurrency FAQ

How do I prevent goroutine leaks?

Every goroutine must have a clear exit: pass context.Context or a done channel, use sync.WaitGroup or errgroup to wait for completion, and always include ctx.Done() in select statements. Without a shutdown mechanism, goroutines accumulate until the process crashes.

Should I use a channel or a mutex?

Use channels to pass data and transfer ownership between goroutines. Use sync.Mutex to protect shared struct fields in critical sections. Use sync.Map for read-heavy concurrent map access. Use atomics for simple counters and flags. Channels communicate ownership; mutexes make ownership implicit.

Why does closing a channel from the receiver panic?

Only the sender should close a channel. If the receiver closes and the sender writes after, it panics. If multiple senders exist, use sync.Once or a separate done channel to coordinate closure.

When should I use errgroup instead of sync.WaitGroup?

Use sync.WaitGroup for fire-and-forget goroutines. Use errgroup.Group when you need to collect errors from goroutines. Use errgroup.WithContext to cancel all siblings when one returns an error. Use errgroup.SetLimit(n) to implement a bounded worker pool.

How do I avoid time.After leaks in loops?

Each time.After call allocates a timer. In hot loops, use time.NewTimer once and call Reset() to reuse it, avoiding allocation churn and potential goroutine leaks from abandoned timers.

Full instructions (SKILL.md)

Source of truth, from samber/cc-skills-golang.

name: golang-concurrency description: "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)." user-invocable: true license: MIT compatibility: Designed for Claude Code, Codex or similar harness, and for projects using Golang. metadata: author: samber version: "1.2.1" openclaw: emoji: "⚡" homepage: https://github.com/samber/cc-skills-golang requires: bins: - go install: [] allowed-tools: Read Edit Write Glob Grep Bash(go:) Bash(golangci-lint:) Bash(git:*) Agent AskUserQuestion paths:

"**/*.go"

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

Related skills

More from samber/cc-skills-golang and the wider catalog.

golang-context

samber/cc-skills-golang

Idiomatic context.Context propagation, cancellation, timeouts, and request-scoped values in Go.

40k installsAudited

golang-continuous-integration

samber/cc-skills-golang

GitHub Actions CI/CD pipeline configuration for Go projects with test, lint, SAST, coverage, and release automation.

39k installs

golang-data-structures

samber/cc-skills-golang

Understand Go data structure internals to choose and optimize slices, maps, arrays, and containers correctly.

40k installsAudited

golang-database

samber/cc-skills-golang

Comprehensive Go database access guide for PostgreSQL, MySQL, MariaDB, and SQLite using database/sql, sqlx, or pgx.

40k installsAudited

golang-dependency-injection

samber/cc-skills-golang

Comprehensive guide to dependency injection patterns and libraries in Go.

39k installsAudited

golang-dependency-management

samber/cc-skills-golang

Manage Go dependencies: go.mod, go.sum, version selection, conflict resolution, and vulnerability scanning.

39k installsAudited