golang-dependency-management

Every outside package a Go project pulls in is a long-term commitment; this is how to decide whether to take one on, upgrade it without breaking the build, and check it for known vulnerabilities.

WHEN TO USE

SCOPE

USE FOR

Decide whether a new dependency is worth adding before running go get.
Upgrade dependencies safely with go get -u=patch, then verify with tests and govulncheck.
Resolve a version conflict with a replace, exclude, or retract directive.
Pin CI tool versions like golangci-lint or benchstat with Go 1.24+ tool directives.
Set up a go.work workspace for developing a library alongside its example app.

NOT FOR

Not for fixing an exploitable vulnerability once govulncheck finds one in your code.
Not for wiring Dependabot or Renovate update bots into CI workflows.

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 (8)

Persona: You are a Go dependency steward. You treat every new dependency as a long-term maintenance commitment — you ask whether the standard library already solves the problem before reaching for an external package.

Dependencies:

govulncheck: go install golang.org/x/vuln/cmd/govulncheck@latest

Go Dependency Management

AI Agent Rule: Ask Before Adding Dependencies

Before running go get to add any new dependency, AI agents MUST ask the user for confirmation. AI agents can suggest packages that are unmaintained, low-quality, or unnecessary when the standard library already provides equivalent functionality. Using go get -u to upgrade an existing dependency is safe.

Before proposing a dependency, evaluate:

Does the standard library already cover the use case?
Is the license compatible?
Are there well-known alternatives?
What it does and why it's needed?

The samber/cc-skills-golang@golang-popular-libraries skill contains a curated list of vetted, production-ready libraries. Prefer recommending packages from that list. When no vetted option exists, favor well-known packages from the Go team (golang.org/x/...) or established organizations over obscure alternatives.

Key Rules

go.sum MUST be committed — it records cryptographic checksums of every dependency version, letting go mod verify detect supply-chain tampering. Without it, a compromised proxy could silently substitute malicious code
govulncheck ./... or go tool govulncheck ./... before every release — catches known CVEs in your dependency tree before they reach production
Maintenance status, license compatibility, and stdlib alternatives are important considerations before adding a dependency — every dependency increases attack surface, maintenance burden, and binary size
go mod tidy before every commit that changes dependencies — removes unused modules and adds missing ones, keeping go.mod honest

go.mod & go.sum

Essential Commands

Command	Purpose
`go mod tidy`	Add missing deps, remove unused ones
`go mod download`	Download modules to local cache
`go mod verify`	Verify cached modules match go.sum checksums
`go mod vendor`	Copy deps into `vendor/` directory
`go mod edit`	Edit go.mod programmatically (scripts, CI)
`go mod graph`	Print the module requirement graph
`go mod why`	Explain why a module or package is needed

Vendoring

Use go mod vendor when you need hermetic builds (no network access), reproducibility guarantees beyond checksums, or when deploying to environments without module proxy access. CI pipelines and Docker builds sometimes benefit from vendoring. Run go mod vendor after any dependency change and commit the vendor/ directory.

Installing & Upgrading Dependencies

Adding a Dependency

go get github.com/google/uuid          # Latest version
go get github.com/google/uuid@v1.6.0   # Specific version
go get github.com/google/uuid@latest   # Explicitly latest
go get github.com/google/uuid@<commit> # Specific commit (pseudo-version)

Before pinning a version, inspect the module's available versions, importers, and known vulnerabilities on pkg.go.dev → See samber/cc-skills-golang@golang-pkg-go-dev skill.

Upgrading

go get -u ./...            # Upgrade ALL direct+indirect deps to latest minor/patch
go get -u=patch ./...      # Upgrade to latest patch only (safer)
go get github.com/pkg@v1.5 # Upgrade specific package

Prefer go get -u=patch for routine updates. Patch and minor updates are usually lower risk than major upgrades, but still require review. For dependency updates, run:

go get -u=patch ./...
go mod tidy
go test ./...
go vet ./...
govulncheck ./...   # or: go tool govulncheck ./...

Release notes and changelogs for libraries affecting persistence, serialization, networking, authentication, authorization, cryptography, or public APIs may contain important information about breaking changes.

Removing a Dependency

go get github.com/google/uuid@none  # Mark for removal
go mod tidy                          # Clean up go.mod and go.sum

Installing CLI Tools

For Go 1.24+ modules, pin executable tools in go.mod with tool directives. Do not create a new tools.go blank-import file unless the module must support Go <1.24.

# Add tools to the current module.
go get -tool github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
go get -tool golang.org/x/vuln/cmd/govulncheck@latest
go get -tool golang.org/x/perf/cmd/benchstat@latest

# Run pinned tools reproducibly.
go tool golangci-lint run ./...
go tool govulncheck ./...
go tool benchstat old.txt new.txt

# Install all module-pinned tools into GOBIN/PATH when needed.
go install tool

# Update pinned tools deliberately, then review go.mod/go.sum.
go get -u tool
go mod tidy

go.mod shape for a module targeting Go 1.27 or newer. This is an example target, not a cap; keep the project's actual go directive and do not change it just to add tools.

module example.com/project

go 1.27

tool (
    github.com/golangci/golangci-lint/v2/cmd/golangci-lint
    golang.org/x/vuln/cmd/govulncheck
    golang.org/x/perf/cmd/benchstat
)

For go 1.27 or newer, go mod tidy auto-merges duplicate require blocks and enforces a two-block layout (direct dependencies, then indirect), preserving existing comments — no manual cleanup needed after a merge that introduces a second require block.

For Go <1.24 only, use the legacy tools.go blank-import workaround:

//go:build tools

package tools

import (
    _ "github.com/golangci/golangci-lint/v2/cmd/golangci-lint"
    _ "golang.org/x/vuln/cmd/govulncheck"
)

Rule: Go 1.24+ = tool directives. Go <1.24 = tools.go fallback.

Module target note

When using a newer toolchain, go mod init may create a module with an older default go directive. If the project intentionally targets the newer toolchain's APIs, update the directive deliberately:

go mod edit -go=1.27
go mod tidy

For future Go versions, use the project's intended target version. Do not use APIs newer than the module's go directive until the project explicitly agrees to upgrade it.

Deep Dives

Versioning & MVS — Semantic versioning rules (major.minor.patch), when to increment each number, pre-release versions, the Minimal Version Selection (MVS) algorithm (why you can't just pick "latest"), and major version suffix conventions (v0, v1, v2 suffixes for breaking changes).
Auditing Dependencies — Vulnerability scanning with govulncheck, tracking outdated dependencies, analyzing which dependencies make the binary large (goweight), and distinguishing test-only vs binary dependencies to keep go.mod clean.
Dependency Conflicts & Resolution — Diagnosing version conflicts (what go get does when you request incompatible versions), resolution strategies (replace directives for local development, exclude for broken versions, retract for published versions that should be skipped), and workflows for conflicts across your dependency tree.
Go Workspaces — go.work files for multi-module development (e.g., library + example application), when to use workspaces vs monorepos, and workspace best practices.
Automated Dependency Updates — Setting up Dependabot or Renovate for automatic dependency update PRs, auto-merge strategies (when to merge automatically vs require review), and handling security updates.
Visualizing the Dependency Graph — go mod graph to inspect the full dependency tree, modgraphviz to visualize it, and interactive tools to find which dependency chains cause bloat.

Cross-References

→ See samber/cc-skills-golang@golang-continuous-integration skill for Dependabot/Renovate CI setup
→ See samber/cc-skills-golang@golang-security skill for vulnerability scanning with govulncheck
→ See samber/cc-skills-golang@golang-popular-libraries skill for vetted library recommendations

Quick Reference

# Start a new module
go mod init github.com/user/project

# Add a dependency
go get github.com/google/uuid@v1.6.0

# Upgrade all deps (patch only, safer)
go get -u=patch ./...

# Remove unused deps
go mod tidy

# Check for vulnerabilities
govulncheck ./...   # or: go tool govulncheck ./...

# Check for outdated deps
go list -u -m -json all | go-mod-outdated -update -direct

# Analyze binary size by dependency
goweight

# Understand why a dep exists
go mod why -m github.com/some/module

# Visualize dependency graph
go mod graph | modgraphviz | dot -Tpng -o deps.png

# Verify checksums
go mod verify

Local tool required

1 FOR THE AGENT

01
Install the govulncheck CLI
Install govulncheck with go install golang.org/x/vuln/cmd/govulncheck@latest to scan the dependency tree for known CVEs before release.
```
go install golang.org/x/vuln/cmd/govulncheck@latest
```

Listed as free: Connected services may require an account or charge fees.

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-dependency-management" --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