Go Tool

Go Tool Dependency Management

Manage Go development tool dependencies using the tool directive introduced in Go 1.24. This ensures reproducible builds by tracking tool versions in go.mod — eliminating the old tools.go workaround and version drift across developers and CI.

For detailed per-tool information, see the [reference catalog](${CLAUDESKILLDIR}/../../docs/go-tool-catalog.md).

When to Use

• A Go project needs external code generation or build tools
• Indicator files suggest a tool should be added (.templ, .proto, sqlc.yml, etc.)
• The user explicitly requests adding a Go tool dependency
• Auditing existing tool dependencies for consistency or cleanup
• Migrating from tools.go pattern to the native tool directive

Prerequisites

Before proceeding, verify:

1. go.mod exists: Check for go.mod in the project root. Abort if missing.
2. Go version ≥ 1.24: Read the go directive in go.mod. If the version is below 1.24, inform the user: "The Go tool directive requires Go 1.24+. Update the go directive in go.mod to 1.24 or later."

Workflow: Detect Recommended Tools

Scan the project for indicator files and compare against existing tool declarations in go.mod.

Step 1: Read Existing Tools

Parse go.mod for the tool block to identify already-tracked tools.

Step 2: Scan for Indicator Files

Use Glob to detect files that suggest specific tools:

| Indicator | Tool | Module Path | |-----------|------|-------------| | sqlc.yml / sqlc.yaml / sqlc.json | sqlc | github.com/sqlc-dev/sqlc/cmd/sqlc | | **/*.templ | templ | github.com/a-h/templ/cmd/templ | | swagger.yaml / swagger.json | swag | github.com/swaggo/swag/cmd/swag |

For stringer and enumer, detection requires context: const blocks with iota patterns. These are best suggested when the user is working with enum-like types.

Step 3: Report Findings

Present a table comparing detected recommendations against existing tools:

| Tool | Status | Reason | |------|--------|--------| | templ | Missing | .templ files found but tool not in go.mod | | sqlc | Present | Already tracked in go.mod |

Workflow: Add Tool

Step 1: Install

go get -tool @latest

Replace @latest with a specific version if the user requests one.

Step 2: Tidy

go mod tidy

Step 3: Verify

go tool  --help

Confirm the tool runs without error.

Step 4: Suggest go:generate Directive

Based on the tool, suggest the appropriate //go:generate directive. See the [reference catalog](${CLAUDESKILLDIR}/../../docs/go-tool-catalog.md) for canonical directives per tool.

General pattern:

//go:generate go tool  

Place the directive in the file closest to the generated output.

Workflow: Remove Tool

Step 1: Remove from go.mod

go get -tool @none

Step 2: Tidy

go mod tidy

Step 3: Clean Up

Search for and remove any //go:generate directives that reference the removed tool:

Grep for: //go:generate go tool 

Workflow: Audit Tools

Step 1: List Declared Tools

Parse the tool (...) block from go.mod.

Step 2: Cross-Reference with Source

For each declared tool, search for //go:generate go tool in Go source files.

Step 3: Report

| Tool | In go.mod | Has go:generate | Status | |------|-----------|-----------------|--------| | sqlc | Yes | Yes | OK | | moq | Yes | No | Possibly unused | | templ | No | Yes | Missing from go.mod |

go:generate Best Practices

1. Always use go tool in directives — not a direct binary path. This ensures the version pinned in go.mod is used.
2. Place directives near generated output — in the package that owns the generated code.
3. Run all generators: go generate ./...
4. Commit generated code to version control so builds don't require running generators.
5. One directive per tool invocation — avoid chaining multiple tools in a single directive.

Non-Go Tools

The go tool directive only supports tools written in Go. For non-Go tools (Node.js, Rust, Python), use alternative management:

• Taskfile.yml or Makefile for running non-Go tools
• Docker for tools with complex dependencies

Error Handling

| Condition | Action | |-----------|--------| | No go.mod found | Abort: "Not a Go module — no go.mod found. Run go mod init first." | | Go version fails after install | Check go mod tidy` was run. Verify the module provides a binary at the expected path. |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sgaunet
• Source: sgaunet/claude-plugins
• License: MIT

Install and usage instructions live in the source repository linked above.