apstndb/godoc

go doc Skill

go doc prints documentation comments and signatures for Go packages, symbols (types, funcs, consts, vars), methods, and struct fields. Prefer this documentation view over reading source files — it extracts doc comments and type signatures without implementation noise, works across the module graph, and groups constructors with types.

When this skill is loaded, use ${CLAUDE_SKILL_DIR}/scripts/godoc.sh as the operational interface. Its implementation and --help output are the source of truth for target syntax and for how wrapper targets map to the underlying go doc, go mod download, -C, and fallback behavior. If you need the raw commands behind a wrapper behavior, inspect ${CLAUDE_SKILL_DIR}/scripts/godoc.sh instead of reconstructing them from memory.

Usage

Use the wrapper script instead of go doc directly. It handles @version resolution, auto-fallback for packages not in go.mod, and multi-target batch lookup:

# Single target (same as go doc)
${CLAUDE_SKILL_DIR}/scripts/godoc.sh [flags] package.Symbol.Method

# Explicit package/symbol split with : separator
${CLAUDE_SKILL_DIR}/scripts/godoc.sh [flags] package:Symbol.Method

# @version support
${CLAUDE_SKILL_DIR}/scripts/godoc.sh [flags] package@version[/subpkg][:Symbol]

# Multi-target batch lookup (multiple targets in one command)
${CLAUDE_SKILL_DIR}/scripts/godoc.sh [flags] target1 target2 target3

# List subpackages of a module or package
${CLAUDE_SKILL_DIR}/scripts/godoc.sh --list package@version
${CLAUDE_SKILL_DIR}/scripts/godoc.sh --list package

The : separator

: explicitly separates the package path from the symbol name. Go import paths and symbol names never contain :, so this is always unambiguous.

• pkg:Symbol — two-arg form: go doc pkg Symbol
• pkg: — package doc (explicit)
• [email protected]:Symbol — root symbol at specific version
• [email protected]/codes:Code — subpackage symbol at specific version
• [email protected]/codes: — subpackage doc (explicit, overrides uppercase heuristic)

Without :, the script uses heuristics for @version targets (uppercase = symbol, lowercase = subpackage, lowercase.Uppercase = subpackage.Symbol) or delegates non-@version targets through the wrapper's normal target handling.

Examples

# Standard usage (identical to go doc)
${CLAUDE_SKILL_DIR}/scripts/godoc.sh -short encoding/json
${CLAUDE_SKILL_DIR}/scripts/godoc.sh encoding/json.Decoder

# Explicit : separator
${CLAUDE_SKILL_DIR}/scripts/godoc.sh encoding/json:Decoder
${CLAUDE_SKILL_DIR}/scripts/godoc.sh google.golang.org/grpc/codes:Code

# Packages not in go.mod (auto-fallback; use : when the package path/symbol boundary may be ambiguous)
${CLAUDE_SKILL_DIR}/scripts/godoc.sh github.com/pelletier/go-toml/v2:Marshal

# Specific version (with heuristic)
${CLAUDE_SKILL_DIR}/scripts/godoc.sh google.golang.org/[email protected]/codes.Code
${CLAUDE_SKILL_DIR}/scripts/godoc.sh google.golang.org/[email protected]/DialOption
${CLAUDE_SKILL_DIR}/scripts/godoc.sh -short google.golang.org/grpc@latest

# Specific version (with : separator — explicit, no heuristic)
${CLAUDE_SKILL_DIR}/scripts/godoc.sh google.golang.org/[email protected]:DialOption
${CLAUDE_SKILL_DIR}/scripts/godoc.sh google.golang.org/[email protected]/codes:Code
${CLAUDE_SKILL_DIR}/scripts/godoc.sh google.golang.org/[email protected]/codes:

# Multi-target batch lookup
${CLAUDE_SKILL_DIR}/scripts/godoc.sh encoding/json.Decoder encoding/json.Encoder fmt.Printf
${CLAUDE_SKILL_DIR}/scripts/godoc.sh -short google.golang.org/[email protected]:DialOption google.golang.org/[email protected]:ServerOption

# List subpackages
${CLAUDE_SKILL_DIR}/scripts/godoc.sh --list google.golang.org/[email protected]
${CLAUDE_SKILL_DIR}/scripts/godoc.sh --list net/http

Underlying go doc forms

go doc                              # package doc for current directory
go doc <pkg>                        # package doc (e.g., encoding/json)
go doc <Sym>                        # symbol in current package (capital = current pkg)
go doc <pkg>.<Sym>                  # symbol in a package
go doc <pkg>.<Sym>.<Method>         # method or field of a symbol
go doc <pkg> <Sym>                  # two-arg form (same as above)
go doc <pkg> <Sym>.<Method>         # two-arg form for method

Do not run these forms directly when godoc.sh is available; they are here to explain what the wrapper ultimately delegates to. For exact raw command equivalents, read ${CLAUDE_SKILL_DIR}/scripts/godoc.sh or run it with --help. Prefer : for package/symbol boundaries in examples, especially with semantic import paths such as /v2 or /v9. godoc.sh adds:

godoc.sh <pkg>:<Sym>                # : separator → two-arg form
godoc.sh <pkg>@<ver>[/subpkg]:<Sym> # @version with : separator
godoc.sh target1 target2 ...        # multi-target batch lookup
godoc.sh --list <pkg>[@<ver>]       # list subpackages

Flags

| Flag | Effect | When to use | |------|--------|-------------| | -short | One-line summary per symbol (no doc comments) | Getting a quick overview of what's in a package — like a table of contents | | -all | Show full documentation for every symbol in the package | When you need comprehensive understanding of an entire package | | -src | Show the full source code of a symbol's declaration and body | When you need to see implementation details, not just the signature | | -u | Include unexported symbols, methods, and fields | When debugging internals or understanding private APIs | | -cmd | Treat package main like a regular package (show exported symbols) | Without this flag, go doc on a package main hides exported symbols | | -c | Case-sensitive symbol matching | By default lowercase in queries matches either case; use -c when you need an exact match | | -C dir | Change to dir before running the command | When you want to look up symbols in a different module or directory context |

Common patterns

Explore an unfamiliar module: --list then -short

When encountering a module you haven't used before, start by discovering its package structure:

# What packages does this module have?
${CLAUDE_SKILL_DIR}/scripts/godoc.sh --list google.golang.org/[email protected]

# Then get an overview of the interesting packages
${CLAUDE_SKILL_DIR}/scripts/godoc.sh -short google.golang.org/[email protected]/codes google.golang.org/[email protected]/credentials

--list also works for standard library and packages in go.mod:

${CLAUDE_SKILL_DIR}/scripts/godoc.sh --list net/http

Explore a package: -short then targeted lookups

Do NOT explore a package by calling one target per symbol repeatedly — this is an N+1 anti-pattern. Type-level documentation already shows the doc comment, type definition, all method signatures, and constructors; do not then call <pkg>.<Type>.<Method> for each method.

Stage 1: -short for the table of contents

${CLAUDE_SKILL_DIR}/scripts/godoc.sh -short <pkg>

This gives a one-line-per-symbol overview. For "what API does this package provide?" questions, -short output alone is often the complete answer. You may not need Stage 2 at all.

Stage 2: get full documentation (only if needed)

Only proceed to Stage 2 when you need details beyond what -short shows (doc comments, method signatures, field definitions).

Option A: -all for small/medium packages

If -short shows the package is small or medium-sized (roughly under 500 lines of -all output), read -all output directly:

${CLAUDE_SKILL_DIR}/scripts/godoc.sh -all <pkg>

Option B: -all to file for large packages (recommended for detailed lookups)

For large packages, save -all to a file, then extract what you need:

# Turn 1: save, check size, and find structure — all in one call
${CLAUDE_SKILL_DIR}/scripts/godoc.sh -all <pkg> > /tmp/pkg-doc.txt
wc -l /tmp/pkg-doc.txt
rg -n '^(type \w+ (interface|struct)|func [A-Z])' /tmp/pkg-doc.txt

# Turn 2: extract multiple sections of interest in one call
# (use line numbers from Turn 1's rg output)
echo "=== Pipeline ===" && sed -n '3441,3520p' /tmp/pkg-doc.txt
echo "=== Tx ===" && sed -n '5870,5950p' /tmp/pkg-doc.txt
echo "=== DialOption functions ===" && rg 'DialOption' /tmp/pkg-doc.txt

Option C: multi-target batch lookup for specific symbols

When you want full docs for specific symbols identified from -short, use multi-target:

${CLAUDE_SKILL_DIR}/scripts/godoc.sh <pkg>.Client <pkg>.Options <pkg>.Pipeline <pkg>.Tx

# For a specific version:
${CLAUDE_SKILL_DIR}/scripts/godoc.sh google.golang.org/[email protected]:ServerOption google.golang.org/[email protected]:DialOption google.golang.org/[email protected]:CallOption

For small packages (like golang.org/x/sync/errgroup), -all output is short enough to read directly — you can skip the -short stage entirely.

Only use a method-level target like <pkg>.<Type>.<Method> when the user asks about a specific method and you need its doc comment or when the method signature alone is ambiguous.

Working with package main

go doc on a command package (package main) hides exported symbols by default — the rationale is that commands expose a CLI, not a Go API. Use -cmd to override this:

${CLAUDE_SKILL_DIR}/scripts/godoc.sh -cmd              # show exported symbols in current package main
${CLAUDE_SKILL_DIR}/scripts/godoc.sh -cmd -u           # also include unexported symbols
${CLAUDE_SKILL_DIR}/scripts/godoc.sh -cmd -short       # one-line listing of everything

Investigating unexported internals

When you need to understand private types, methods, or struct fields (for debugging, testing, or code review):

${CLAUDE_SKILL_DIR}/scripts/godoc.sh -u SomeType               # shows unexported fields and methods too
${CLAUDE_SKILL_DIR}/scripts/godoc.sh -u -src someUnexportedFunc # source code of an unexported function

Finding example code

go doc does not show Example functions — they live in _test.go files which go doc excludes. Use go test -list to discover them, then read the source from the module cache or GOROOT.

List available examples:

go test -list 'Example' <pkg>                    # in-module packages
go test -list 'Example' encoding/json             # stdlib

Read example source code:

# stdlib — source is in GOROOT
grep -A 30 'func ExampleDecoder(' "$(go env GOROOT)/src/encoding/json/example_test.go"

# dependency in go.mod — find via go list
grep -A 30 'func ExampleClient(' \
  "$(go list -m -f '{{.Dir}}' google.golang.org/grpc)/example_test.go"

# package not in go.mod — download to cache, then read
DIR=$(GOFLAGS=-mod=mod go mod download -C /tmp -json github.com/redis/go-redis/v9@latest | jq -r '.Dir')
grep -A 30 'func ExampleClient_Pipelined(' "$DIR/example_test.go"

For packages with multiple *_test.go files, find the right one first:

grep -rl 'func Example' "$DIR"/*.go "$DIR"/*_test.go

Public metadata: pkg.go.dev API

pkg.go.dev also provides a JSON API for public module and package metadata such as search, versions, symbols, rendered docs/examples, importers, and vulnerabilities: https://pkg.go.dev/v1beta/api. Use that API when public ecosystem metadata is the better source; keep this skill focused on local go doc/godoc.sh lookups.

Decision guide: which flag combination to use

• "What functions/types does this package have?" → godoc.sh -short <pkg>
• "What does this function do?" → godoc.sh <pkg>.<Func>
• "Show me all methods on this type" → godoc.sh <pkg>.<Type> (or -all for full docs)
• "I need to see the implementation" → godoc.sh -src <pkg>.<Sym>
• "Show me example code" → go test -list 'Example' <pkg> then grep the source; use the pkg.go.dev API for rendered public examples
• "Include private stuff too" → add -u
• "This is a main package" → add -cmd
• "What's in this whole package?" → godoc.sh -all <pkg>
• "Docs for a specific version" → godoc.sh <pkg>@<version>:Symbol or <pkg>@<version>/subpkg:Symbol
• "What subpackages does this module have?" → godoc.sh --list <pkg> or godoc.sh --list <pkg>@<version>
• "Multiple symbols at once" → godoc.sh target1 target2 target3
• "Package not in go.mod" → just use godoc.sh — it auto-fallbacks