golang-gopls

SKILL.md

Persona: You are a Go engineer who reaches for semantic code intelligence instead of grep whenever a question is about the resolved build — grep finds text, gopls finds meaning (types, call graphs, shadowing, implementation relationships).

Dependencies: gopls — go install golang.org/x/tools/gopls@latest (v0.20+). The native LSP tool additionally needs ENABLE_LSP_TOOL=1 and the gopls-lsp@claude-plugins-official marketplace plugin (see references/mcp.md).

gopls is the official Go language server. It only answers questions about your specific, locally resolved build — your workspace plus every dependency exactly as pinned in go.sum, including replace directives. For a package that isn't part of that build (versions, docs, licenses, CVEs of something you haven't added yet), → See samber/cc-skills-golang@golang-pkg-go-dev skill (godig) instead.

Three ways to reach gopls

Not interchangeable — pick by what you already know and what you need back:

gopls's own MCP server (preferred for most tasks) — purpose-built for agents: tools take names, file paths, and fuzzy queries instead of raw cursor positions. Register once per machine: claude mcp add gopls -- gopls mcp. Runs headless over stdio, no editor attached, only sees files saved to disk — the right default for an agent-only workflow. See references/mcp.md for every tool.

The native LSP tool — Claude Code's built-in editor-style integration. Off by default: set ENABLE_LSP_TOOL=1, install gopls, and install the official gopls-lsp@claude-plugins-official marketplace plugin to wire it as the Go language server. Operations (goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, call hierarchy) are keyed by line/character, so they're most useful once you already have a location — typically right after a grep or a read. Unique value: compiler diagnostics are pushed into context automatically after every edit, no explicit call needed.

The gopls CLI — same engine, invoked as gopls <command> <file:line:col>. The Go team documents it as experimental and debugging-only — "not efficient, complete, flexible, or officially supported." Use it when neither MCP nor the native tool is wired up, or for a one-shot scripted check. Positions are file:line:col (1-indexed, UTF-8 bytes) or file:#offset (0-indexed). See references/cli.md.

Preference order: MCP → native LSP → CLI. MCP tools match how an agent thinks (by name/path, not cursor position); the native tool adds free automatic diagnostics; the CLI is the documented fallback of last resort. Wire as many as are available and let the task pick the tool — a query you already have a line:col for is cheap via LSP, a "where is X" query is cheap via go_search, a quick unattended check is cheap via the CLI.

Capability → CLI → MCP → native LSP

Full mapping of every capability to its CLI command, MCP tool, and native LSP op: references/matrix.md.