golang-lint

Set up the tool that scans Go code for suspicious patterns, and make sense of what it reports — including how to turn it on for an old codebase without drowning in warnings.

WHEN TO USE

SCOPE

USE FOR

Write a production-ready .golangci.yml instead of starting from an empty config.
Suppress a specific false-positive warning with a properly justified nolint comment.
Interpret a lint output line and trace it back to the linter that raised it.
Adopt linting on a legacy codebase without drowning in thousands of pre-existing issues.

NOT FOR

Not for wiring a lint step into a GitHub Actions CI pipeline.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (10)

Persona: You are a Go code quality engineer. You treat linting as a first-class part of the development workflow — not a post-hoc cleanup step.

Orchestration mode: Fan out the five sub-agents described in the "Parallelizing Legacy Codebase Cleanup" section (auto-fix, security linters, error handling, style/formatting, code quality) when adopting linting on a legacy codebase, so independent linter categories are fixed concurrently. On Claude Code, use ultracode to opt into multi-agent orchestration explicitly.

Modes:

Setup mode — configuring .golangci.yml, choosing linters, enabling CI: follow the configuration and workflow sections sequentially.
Coding mode — writing new Go code: launch a background agent running golangci-lint run --fix on the modified files only while the main agent continues implementing the feature; surface results when it completes.
Interpret/fix mode — reading lint output, suppressing warnings, fixing issues on existing code: start from "Interpreting Output" and "Suppressing Lint Warnings"; use parallel sub-agents for large-scale legacy cleanup.

Dependencies:

golangci-lint: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Go Linting

Overview

golangci-lint is the standard Go linting tool. It aggregates 100+ linters into a single binary, runs them in parallel, and provides a unified configuration format. Run it frequently during development and always in CI.

Every Go project MUST have a .golangci.yml — it is the source of truth for which linters are enabled and how they are configured. See the recommended configuration for a production-ready setup with 48 linters enabled.

Quick Reference

# Run all configured linters
golangci-lint run ./...

# Auto-fix issues where possible
golangci-lint run --fix ./...

# Format code (golangci-lint v2+)
golangci-lint fmt ./...

# Run a single linter only
golangci-lint run --enable-only govet ./...

# List all available linters
golangci-lint linters

# Verbose output with timing info
golangci-lint run --verbose ./...

Configuration

The recommended .golangci.yml provides a production-ready setup with 33 linters. For configuration details, linter categories, and per-linter descriptions, see the linter reference — which linters check for what (correctness, style, complexity, performance, security), descriptions of all 33+ linters, and when each one is useful.

Suppressing Lint Warnings

Use //nolint directives sparingly — fix the root cause first.

// Good: specific linter + justification
//nolint:errcheck // fire-and-forget logging, error is not actionable
_ = logger.Sync()

// Bad: blanket suppression without reason
//nolint
_ = logger.Sync()

Rules:

//nolint directives MUST specify the linter name: //nolint:errcheck not //nolint
//nolint directives MUST include a justification comment: //nolint:errcheck // reason
The nolintlint linter enforces both rules above — it flags bare //nolint and missing reasons
NEVER suppress security linters (gosec, bodyclose, sqlclosecheck) without a very strong reason

For comprehensive patterns and examples, see nolint directives — when to suppress, how to write justifications, patterns for per-line vs per-function suppression, and anti-patterns.

Development Workflow

Linters SHOULD be run after every significant change: golangci-lint run ./...
Auto-fix what you can: golangci-lint run --fix ./...
Format before committing: golangci-lint fmt ./...
Incremental adoption on legacy code: set issues.new-from-rev in .golangci.yml to only lint new/changed code, then gradually clean up old code

Makefile targets (recommended):

lint:
	golangci-lint run ./...

lint-fix:
	golangci-lint run --fix ./...

fmt:
	golangci-lint fmt ./...

For CI pipeline setup (GitHub Actions with golangci-lint-action), see the samber/cc-skills-golang@golang-continuous-integration skill.

Interpreting Output

Each issue follows this format:

path/to/file.go:42:10: message describing the issue (linter-name)

The linter name in parentheses tells you which linter flagged it. Use this to:

Look up the linter in the reference to understand what it checks
Suppress with //nolint:linter-name // reason if it's a false positive
Use golangci-lint run --verbose for additional context and timing

Common Issues

Problem	Solution
"deadline exceeded"	Set or increase `run.timeout` in `.golangci.yml`; golangci-lint v2 defaults to no timeout (`0`)
Too many issues on legacy code	Set `issues.new-from-rev: HEAD~1` to lint only new code
Linter not found	Check `golangci-lint linters` — linter may need a newer version
Conflicts between linters	Disable the less useful one with a comment explaining why
v1 config errors after upgrade	Run `golangci-lint migrate` to convert config format
Slow on large repos	Reduce `run.concurrency` or exclude paths with `linters.exclusions.paths` / `formatters.exclusions.paths`

Parallelizing Legacy Codebase Cleanup

When adopting linting on a legacy codebase, use up to 5 parallel sub-agents to fix independent linter categories simultaneously:

Sub-agent 1: Run golangci-lint run --fix ./... for auto-fixable issues
Sub-agent 2: Fix security linter findings (bodyclose, sqlclosecheck, gosec)
Sub-agent 3: Fix error handling issues (errcheck, nilerr, wrapcheck)
Sub-agent 4: Fix style and formatting (gofumpt, goimports, revive)
Sub-agent 5: Fix code quality (gocritic, unused, ineffassign)

Cross-References

→ See samber/cc-skills-golang@golang-continuous-integration skill for CI pipeline with golangci-lint-action
→ See samber/cc-skills-golang@golang-code-style skill for style rules that linters enforce
→ See samber/cc-skills-golang@golang-security skill for SAST tools beyond linting (gosec, govulncheck)
→ See samber/cc-skills-golang@golang-continuous-integration skill for automated AI-driven code review in CI using these guidelines

Local tool required

1 FOR THE AGENT

01
Install the golangci-lint CLI
Install golangci-lint with go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest before running or configuring it.
```
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
```

Listed as free: Connected services may require an account or charge fees.
Installation: One command — usually under 2 minutes.

This skill ships inside the Samber Golang Skills plugin.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add samber/cc-skills-golang --skill "golang-lint" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the Samber Golang Skills plugin package selected for your AI tool.

Add Samuel's marketplace, then install the plugin

Type both lines inside a Claude Code session, not at your shell prompt. The marketplace is a separate repository of Samuel Berthe's, samber/cc, which also lists his other plugins. The second line opens the details of cc-skills-golang, which carries this repository's 46 Go skills; pick one of the install options shown and Claude Code installs it.

01
```
/plugin marketplace add samber/cc
```
02
```
/plugin install cc-skills-golang@samber
```

Run it in your terminal. It copies the whole repository, with its 46 skills, into ~/.openclaw/skills/cc-skills-golang, OpenClaw's skills folder in your home folder. To install it for one OpenClaw workspace instead, Samuel gives ~/.openclaw/workspace/skills/cc-skills-golang as the folder.

git clone https://github.com/samber/cc-skills-golang.git ~/.openclaw/skills/cc-skills-golang

Run it in your terminal, not inside Gemini CLI; installing from GitHub needs git on your computer. It installs the repository, with its 46 skills, as a Gemini CLI extension. To update it later, run gemini extensions update cc-skills-golang.

gemini extensions install https://github.com/samber/cc-skills-golang

Run it in your terminal. It copies the whole repository, with its 46 skills, into ~/.cursor/skills/cc-skills-golang, Cursor's skills folder in your home folder.

git clone https://github.com/samber/cc-skills-golang.git  ~/.cursor/skills/cc-skills-golang

Type it in an interactive GitHub Copilot CLI session, not at your shell prompt. It installs the repository straight from GitHub as a plugin, with its 46 skills and no marketplace to add first.

/plugin install https://github.com/samber/cc-skills-golang

Run it in your terminal. It copies the whole repository, with its 46 skills, into ~/.agents/skills/cc-skills-golang in your home folder.

git clone https://github.com/samber/cc-skills-golang.git ~/.agents/skills/cc-skills-golang

Open plugin page ↗

What's inside

Files included with this skill.

View on GitHub

Same repository

golang-benchmark
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.Read full description
golang-cli
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.Read full description
golang-code-style
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).Read full description
golang-concurrency
Golang concurrency patterns. Use when writing or reviewing concurrent Go code involving goroutines, channels, select, locks, sync primitives, errgroup, singleflight, worker pools, or fan-out/fan-in pipelines. Also triggers when you detect goroutine leaks, race conditions, channel ownership issues, or need to choose between channels and mutexes.Read full description
golang-context
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.Read full description
golang-continuous-integration
CI/CD pipeline configuration using GitHub Actions for Golang projects — testing, linting, SAST, security scanning, code coverage, Dependabot, Renovate, GoReleaser, code review automation, and release pipelines. Use when setting up or improving Go project CI, configuring GitHub Actions workflows, adding linters or security scanners, automating dependency updates, or adding quality gates.Read full description

Go Linting

Overview

Quick Reference

Configuration

Suppressing Lint Warnings

Development Workflow

Interpreting Output

Common Issues

Parallelizing Legacy Codebase Cleanup

Cross-References

Local tool required

Install just this skill

Install the whole plugin

Add Samuel's marketplace, then install the plugin

What's inside

More skills

golang-benchmark

golang-cli

golang-code-style

golang-concurrency

golang-context

golang-continuous-integration