How do I install the Asdf Go Setup skill?

Run npx skillmds@latest add indradhanush/asdf-go-setup in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Asdf Go Setup safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Asdf Go Setup?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Asdf Go Setup free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Asdf Go Setup?

indradhanush (@indradhanush) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Asdf Go Setup by indradhanush — Agent Skill

Name: Asdf Go Setup
Author: indradhanush

Asdf Go Setup

Install and configure gopls for a Go project that uses asdf to manage the Go version. Use this whenever gopls fails to start for a project, an editor reports "No version is set for command gopls", or a new Go project needs LSP set up with asdf. Accepts a project path as args; detects the correct Go version from .tool-versions or go.mod automatically.

indradhanush dfb6f10 2.9 KB Updated Sep 17, 2026

File contents

asdf Go Setup

Install gopls into the right location for a project's asdf-managed Go version.

Background

asdf's golang plugin only scans bin/ and go/bin/ inside an install (via list-bin-paths). gopls must live at:

$ASDF_DIR/installs/golang/<version>/bin/gopls

go install without an explicit GOBIN puts the binary in $GOPATH/bin (packages/bin/), which asdf never finds. The fix is to set both GOBIN and GOPATH explicitly.

Steps

1. Resolve the project path

Use args if provided; default to the current working directory.

2. Detect the Go version

Check in order, stopping at the first match:

<path>/.tool-versions — look for a line starting with golang
<path>/go.mod — read the go directive (e.g. go 1.22.12)
~/.tool-versions — global asdf fallback

If no version is found anywhere, report the gap and stop. Do not guess.

# From .tool-versions
grep '^golang ' <path>/.tool-versions | awk '{print $2}'

# From go.mod
grep '^go ' <path>/go.mod | awk '{print $2}'

3. Locate ASDF_DIR

echo "${ASDF_DIR:-$HOME/.asdf}"

4. Verify the version is installed

asdf list golang | grep -F "<version>"

If missing, tell the user to run asdf install golang <version> and stop.

5. Check whether gopls is already installed

ls "$ASDF_DIR/installs/golang/<version>/bin/gopls" 2>/dev/null

If the binary exists, skip to step 7.

6. Install gopls

Use the Go binary for that exact version so the module cache stays isolated:

GOBIN="$ASDF_DIR/installs/golang/<version>/bin" \
GOPATH="$ASDF_DIR/installs/golang/<version>/packages" \
  "$ASDF_DIR/installs/golang/<version>/go/bin/go" install \
  golang.org/x/tools/gopls@latest

Note: gopls >= v0.22 requires Go >= 1.26. If the project version is older, Go will auto-switch via GOTOOLCHAIN to a newer installed version. This is expected and harmless — the binary still lands in the project version's bin/ directory.

Then reshim:

asdf reshim golang <version>

7. Verify

Run this from inside the project path:

cd <path> && asdf which gopls

Expected output: $ASDF_DIR/installs/golang/<version>/bin/gopls

If it still fails, check that <path>/.tool-versions contains golang <version> — the shim uses that file to resolve which version to serve.

8. Report

Tell the user:

which Go version was detected and from which file
whether gopls was freshly installed or already present
the verified path returned by asdf which gopls

---name: asdf-go-setupdescription: Install and configure gopls for a Go project that uses asdf to manage the Go version. Use this whenever gopls fails to start for a project, an editor reports "No version is set for command gopls", or a new Go project needs LSP set up with asdf. Accepts a project path as args; detects the correct Go version from .tool-versions or go.mod automatically.---# asdf Go SetupInstall gopls into the right location for a project's asdf-managed Go version.## Backgroundasdf's golang plugin only scans `bin/` and `go/bin/` inside an install(via `list-bin-paths`). gopls must live at:```$ASDF_DIR/installs/golang/<version>/bin/gopls````go install` without an explicit `GOBIN` puts the binary in `$GOPATH/bin`(`packages/bin/`), which asdf never finds. The fix is to set both `GOBIN`and `GOPATH` explicitly.## Steps### 1. Resolve the project pathUse `args` if provided; default to the current working directory.### 2. Detect the Go versionCheck in order, stopping at the first match:1. `<path>/.tool-versions` — look for a line starting with `golang `2. `<path>/go.mod` — read the `go` directive (e.g. `go 1.22.12`)3. `~/.tool-versions` — global asdf fallbackIf no version is found anywhere, report the gap and stop. Do not guess.```bash# From .tool-versionsgrep '^golang ' <path>/.tool-versions | awk '{print $2}'# From go.modgrep '^go ' <path>/go.mod | awk '{print $2}'```### 3. Locate ASDF_DIR```bashecho "${ASDF_DIR:-$HOME/.asdf}"```### 4. Verify the version is installed```bashasdf list golang | grep -F "<version>"```If missing, tell the user to run `asdf install golang <version>` and stop.### 5. Check whether gopls is already installed```bashls "$ASDF_DIR/installs/golang/<version>/bin/gopls" 2>/dev/null```If the binary exists, skip to step 7.### 6. Install goplsUse the Go binary for that exact version so the module cache stays isolated:```bashGOBIN="$ASDF_DIR/installs/golang/<version>/bin" \GOPATH="$ASDF_DIR/installs/golang/<version>/packages" \ "$ASDF_DIR/installs/golang/<version>/go/bin/go" install \ golang.org/x/tools/gopls@latest```Note: gopls >= v0.22 requires Go >= 1.26. If the project version is older,Go will auto-switch via `GOTOOLCHAIN` to a newer installed version. This isexpected and harmless — the binary still lands in the project version's`bin/` directory.Then reshim:```bashasdf reshim golang <version>```### 7. VerifyRun this from inside the project path:```bashcd <path> && asdf which gopls```Expected output: `$ASDF_DIR/installs/golang/<version>/bin/gopls`If it still fails, check that `<path>/.tool-versions` contains`golang <version>` — the shim uses that file to resolve which version toserve.### 8. ReportTell the user:- which Go version was detected and from which file- whether gopls was freshly installed or already present- the verified path returned by `asdf which gopls`

Frequently asked questions