go-version-manager
Detect, select, switch, and verify Go toolchains for a repository without mutating global system state. Use when a Go build reports an incompatible GOROOT or standard-library package, when go.mod/go.sum behavior differs across Go versions, when multiple Go versions are installed, when choosing a Go binary for go mod tidy/test/build, or when setting up a repeatable multi-version Go workflow.
How do I install this agent skill?
npx skills add https://github.com/mnhkahn/cyeam-cli --skill go-version-managerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a secure way to manage Go toolchains by selecting the appropriate local binary based on a project's go.mod file. It adheres to security best practices by avoiding global system modifications, requiring user consent for local changes, and relying on pre-installed binaries rather than performing automatic downloads.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Go Version Manager
Choose the project-compatible Go toolchain before changing dependencies. Prefer the machine's existing goenv installation for real version switching. Fall back to explicit binary paths when no supported version manager is available.
Workflow
- Read
go.modcompletely enough to identifygo,toolchain, andreplacedirectives. - Run
.agents/skills/go-version-manager/scripts/go-version-manager.sh requirement <project-dir>,manager, andlist. - Run
.agents/skills/go-version-manager/scripts/go-version-manager.sh select <project-dir>to choose an installed binary. - Confirm the selected binary with
<go-binary> versionand<go-binary> env GOROOT GOTOOLCHAIN GOPATH GOMODCACHE GOCACHE. - Choose the switching scope:
- For one command, use the script's
execcommand. Withgoenv, it setsGOENV_VERSIONonly for that command. - For the current terminal, run the command printed by
shell-command(normallygoenv shell <version>). - For a repository-persistent selection, use
switch-local; this runsgoenv local <version>and writes.go-version, so do it only when the user authorizes a repository change. - Change
goenv globalonly when the user explicitly requests a machine-wide default change.
- For one command, use the script's
- Review
git diff -- go.mod go.sumafter any module command. - Report the selected version, commands run, dependency changes, and verification result.
Selection rules
- Prefer an exact
toolchain goX.Y.Zinstallation. - Otherwise prefer the highest installed patch within the
go X.Yminor line. - Treat the
godirective as the minimum language/toolchain requirement, not permission to upgrade the module directive. - Use a newer minor only when no compatible same-minor installation exists, and explain the risk before module mutations.
- Do not set
GOROOTfor a normal Go installation; the selectedgobinary determines it. - Do not rewrite
/usr/local/go, system symlinks, shell profiles, or global PATH unless explicitly requested. - Prefer an installed
goenvand its installed versions. Honor another existing version manager (mise,asdf,g,gvm, Homebrew) when the repository already configures one. Do not introduce a second manager without approval. - Do not automatically install a missing Go version. Report the missing version and ask before downloading or installing tools.
Module safety
- Never hand-edit
go.sumto silence missing checksum errors. - Run
go mod tidyonly with the selected project-compatible toolchain and when the task authorizes dependency-file changes. - Prefer
go mod downloador the error's narrowly scopedgo get module@versionwhen only fetching an existing graph is required; inspect resulting diffs. - Do not upgrade packages merely to compensate for using the wrong local Go version.
- Do not change the
goortoolchaindirective unless the user requests a project toolchain upgrade. - Preserve unrelated user changes in
go.modandgo.sum.
Diagnose common failures
package slices is not in GOROOT: the active Go binary is older than Go 1.21. Switch toolchains before touching dependencies.missing go.sum entry: use the correct toolchain, then fetch or tidy the module graph; do not write checksums manually.- Cache
operation not permitted: keep the selected toolchain and redirect only writable caches, for exampleGOCACHE=<writable-temp-dir>. RedirectGOMODCACHEonly when necessary because it can trigger full dependency downloads. - Mock/test binary requires special flags or external services: distinguish compilation from execution. Use
go test -c -o <temp-file> <package>for compile-only verification when package initialization prevents local execution. - A command unexpectedly changes many dependencies: stop, inspect
go version,go env GOTOOLCHAIN, module directives, and the diff before proceeding.
Verification ladder
Use the lowest sufficient level, then escalate by risk:
<go> versionand<go> env ...<go> mod verify- Targeted
<go> test ./path/to/changed/package - Compile-only
<go> test -c -o <temp-file> ./package - Broader
go test ./...or project build command
If dependency downloads or writes outside the workspace require approval, request it rather than bypassing sandbox or network controls.
Script
Use .agents/skills/go-version-manager/scripts/go-version-manager.sh:
# Show go/toolchain requirements
.agents/skills/go-version-manager/scripts/go-version-manager.sh requirement /path/to/project
# List discovered Go binaries
.agents/skills/go-version-manager/scripts/go-version-manager.sh list
# Show which switching backend is available
.agents/skills/go-version-manager/scripts/go-version-manager.sh manager
# Print the selected Go binary
.agents/skills/go-version-manager/scripts/go-version-manager.sh select /path/to/project
# Execute with the selected binary
.agents/skills/go-version-manager/scripts/go-version-manager.sh exec /path/to/project -- test ./...
# Print the command that switches the current terminal
.agents/skills/go-version-manager/scripts/go-version-manager.sh shell-command /path/to/project
# Persist the selection for this repository (writes .go-version)
.agents/skills/go-version-manager/scripts/go-version-manager.sh switch-local /path/to/project
The script is read-only except for switch-local, which writes .go-version, and effects caused by the Go subcommand supplied to exec.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/mnhkahn/cyeam-cli/go-version-manager">View go-version-manager on skillZs</a>