golang-how-to
The golang-how-to skill orchestrates Go development by automatically loading multiple relevant skills based on task context. Use it for any Go coding, review, debug, or setup task where the orchestrator identifies the primary skill and all applicable secondary skills to load simultaneously, such as loading golang-grpc plus golang-testing plus golang-error-handling for gRPC service development, or disambiguating overlapping skills when task intent is unclear.
git clone --depth 1 https://github.com/samber/cc-skills-golang /tmp/golang-how-to && cp -r /tmp/golang-how-to/skills/golang-how-to ~/.claude/skills/golang-how-toSKILL.md
**Persona:** You are a Go skills orchestrator. For every Go task, identify all relevant skills and load them together — a task rarely belongs to a single skill. **Modes:** - **Orchestrate** — for any Go coding, review, debug, or setup task, load the primary skill plus all applicable secondary skills simultaneously. - **Disambiguate** — when two skills seem to overlap, show the boundary table. See [disambiguation.md](references/disambiguation.md). - **Configure** — write the always-load directive for `golang-how-to` itself, plus an optional `## Required Go skills` block, to the project's agent-config file (CLAUDE.md, AGENTS.md, or equivalent). Follow [project-config.md](references/project-config.md). **Questions:** In Configure mode, ask the user through the environment's question tool — never as plain-text prose. One question at a time, wait for the answer. If the environment has no question tool, ask in prose with the same options. **Dependencies:** `gopls` — `go install golang.org/x/tools/gopls@latest`; Claude Code's built-in `LSP` tool also needs `ENABLE_LSP_TOOL=1` and a Go language server wired (see [Code navigation with gopls](#code-navigation-with-gopls)). ## Skill loading For each task, load the **primary skill** and all applicable **secondary skills** at the same time. Do not wait — load them together at the start. | Intent | Primary | Also load | | --- | --- | --- | | Design an API, choose a pattern | `golang-design-patterns` | `golang-structs-interfaces`, `golang-naming` | | Name a type, function, or package | `golang-naming` | `golang-code-style` | | Handle errors idiomatically | `golang-error-handling` | `golang-safety` (nil-heavy code) | | Write goroutines, channels, sync | `golang-concurrency` | `golang-context` (if cancellation) | | Pass deadlines / cancel operations | `golang-context` | `golang-concurrency` (if goroutines) | | Design structs, embed, use interfaces | `golang-structs-interfaces` | `golang-design-patterns` | | Database queries and transactions | `golang-database` | `golang-error-handling`, `golang-security` | | Build a gRPC service | `golang-grpc` | `golang-testing`, `golang-error-handling` | | Build a GraphQL API | `golang-graphql` | `golang-testing`, `golang-error-handling` | | Build a CLI command tree | `golang-spf13-cobra` | `golang-cli`, `golang-spf13-viper` (if config) | | Layer config from flags/env/file | `golang-spf13-viper` | `golang-spf13-cobra` | | Write tests | `golang-testing` | `golang-stretchr-testify` (if using testify) | | Apply optimization patterns | `golang-performance` | `golang-benchmark` (measure first) | | Measure with pprof / benchstat | `golang-benchmark` | `golang-performance` (fix), `golang-troubleshooting` (root cause) | | Debug a panic or unexpected behavior | `golang-troubleshooting` | `golang-safety`, `golang-benchmark` (if perf-related) | | Monitor in production | `golang-observability` | `golang-performance` (if SLO breach) | | Audit security vulnerabilities | `golang-security` | `golang-safety`, `golang-lint` | | Review formatting and style | `golang-code-style` | `golang-naming`, `golang-lint` | | Refactor or restructure existing code | `golang-refactoring` | `golang-naming`, `golang-code-style`, `golang-project-layout` | | Configure golangci-lint | `golang-lint` | `golang-code-style` | | Write godoc / README / CHANGELOG | `golang-documentation` | `golang-naming` | | Set up a new project structure | `golang-project-layout` | `golang-design-patterns`, `golang-dependency-injection`, `golang-lint` | | Set up CI/CD pipeline | `golang-continuous-integration` | `golang-lint`, `golang-security` | | Choose a library | `golang-popular-libraries` | relevant library-specific skill | | Look up a package's docs, versions, importers, or CVEs | `golang-pkg-go-dev` | `golang-dependency-management` | | Navigate, diagnose, or refactor local code (definitions, references, rename) | `golang-gopls` | — | | Adopt new Go language features | `golang-modernize` | `golang-lint` | | Use samber/lo (slice/map helpers) | `golang-samber-lo` | `golang-data-structures`, `golang-performance` | | Use samber/oops (structured errors) | `golang-samber-oops` | `golang-error-handling` | | Use log/slog | `golang-samber-slog` | `golang-observability`, `golang-error-handling` | | Use dependency injection | `golang-dependency-injection` | `golang-google-wire` or `golang-uber-dig` or `golang-uber-fx` or `golang-samber-do` | All skill identifiers above are short forms of `samber/cc-skills-golang@<name>`. ## Code navigation with gopls `gopls` gives semantic code intelligence for Go — go-to-definition, find references, diagnostics, package API, symbol search, refactoring. → See `samber/cc-skills-golang@golang-gopls` skill for the three ways to reach it (its own MCP server, the native `LSP` tool, and its CLI), the full capability matrix, and efficient read/edit workflows. `gopls` only reasons about code that is present and resolvable in the local build: your workspace plus every dependency exactly as pinned in `go.sum` (including `replace` directives). For any fact that isn't tied to your local build — version history, licenses, ecosystem-wide importers, a package you haven't added yet — use `golang-pkg-go-dev` (`godig`). See the `godig` vs gopls vs Context7 vs govulncheck section below for the full boundary. ## `godig` vs gopls vs Context7 vs govulncheck Four tools can answer "is this dependency OK to use," and they don't overlap as much as they look: - **Context7** is a general-purpose, cross-language documentation fetcher — useful when no more specific source exists. For a Go package or module, `godig` is almost always the better choice: it pulls **structured, Go-specific data** straight from pkg.go.dev — exact versions, exported symbols with signatures, runnable examples, `imported-by`, and known vulnerabilities — rather than Context7's generic scraped/curated docs, which don't expose that structure and can lag or miss lesser-known Go modules. Reach
Golang benchmarking, profiling, and performance measurement. Use when writing, running, or comparing Go benchmarks, profiling hot paths with pprof, interpreting CPU/memory/trace profiles, analyzing results with benchstat, setting up CI benchmark regression detection, or investigating production performance with Prometheus runtime metrics. Also use when the developer needs deep analysis on a specific performance indicator - this skill provides the measurement methodology, while `samber/cc-skills-golang@golang-performance` provides the optimization patterns.
Golang CLI application development. Use when building, modifying, or reviewing a Go CLI tool — especially for command structure, flag handling, configuration layering, version embedding, exit codes, I/O patterns, signal handling, shell completion, argument validation, and CLI unit testing. Also triggers when code uses cobra, viper, or urfave/cli. For cobra-specific APIs → See `samber/cc-skills-golang@golang-spf13-cobra` skill; for viper configuration layering → See `samber/cc-skills-golang@golang-spf13-viper` skill.
Golang code style conventions — line length and breaking, variable declarations, control flow clarity, when comments help vs hurt. Use when writing or reviewing Go code, asking about style or clarity, or establishing project coding standards. Not for naming conventions (→ See `samber/cc-skills-golang@golang-naming` skill), linter configuration (→ See `samber/cc-skills-golang@golang-lint` skill), or doc comments (→ See `samber/cc-skills-golang@golang-documentation` skill).
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).
Idiomatic context.Context usage in Golang — propagation through API boundaries, cancellation, timeouts and deadlines, request-scoped values, context.WithoutCancel for background work outliving requests. Apply when designing context propagation across layers, debugging leaked or unexpired contexts, choosing between context.Background/TODO/WithoutCancel, or storing values in context. Not for code that merely accepts ctx as first parameter.
GitHub Actions CI/CD pipeline configuration for Golang projects — workflow files for test, lint, SAST, coverage and vulnerability-scan jobs, Dependabot and Renovate config files, GoReleaser release pipelines, Docker build/push, repository security settings, and AI-driven PR review. Use when setting up or improving Go project CI, writing or fixing `.github/workflows/*.yml`, adding a linter or security scanner as a pipeline job, wiring automated dependency-update bots, or adding quality gates. Covers wiring tools into a pipeline, not the analysis they perform: do NOT use for choosing or interpreting security findings (→ See `samber/cc-skills-golang@golang-security` skill) or for choosing, upgrading, or auditing dependency versions (→ See `samber/cc-skills-golang@golang-dependency-management` skill).
Golang data structures — slices (internals, capacity growth, preallocation, slices package), maps (internals, hash buckets, maps package), arrays, container/list/heap/ring, strings.Builder vs bytes.Buffer, generic collections, pointers (unsafe.Pointer, weak.Pointer), and copy semantics. Use when choosing or optimizing Go data structures, implementing generic containers, using container/ packages, unsafe or weak pointers, or questioning slice/map internals. Not for applying optimization patterns once profiling has identified a bottleneck (→ See `samber/cc-skills-golang@golang-performance` skill).
Comprehensive guide for Go database access — parameterized queries, struct scanning, NULLable columns, transactions, isolation levels, SELECT FOR UPDATE, connection pool, batch processing, context propagation, and migration tooling. Use when writing, reviewing, or debugging Golang code that interacts with PostgreSQL, MariaDB, MySQL, or SQLite; for database testing; or for questions about database/sql, sqlx, or pgx. Does NOT generate database schemas or migration SQL.