| name | go-ultimate |
| description | The complete Go development skill. REQUIRED for ALL Go work — writing, refactoring, reviewing, generating, scaffolding, or discussing Go code, including any change to .go files. Use whenever the user mentions Go, Golang, go.mod, a Go package, or asks to build a Go backend service, CLI, library, script, MCP server (Model Context Protocol), or AI/LLM agent with tool calling or ReAct-style reasoning. Routes by project type to the right architecture, conventions, and review checklist. Highly opinionated; overrides generic Go style and lint guidance on conflicts.
|
| user-invocable | true |
| license | MIT |
| compatibility | Designed for Claude Code, ZCode, or similar AI coding agents, and for any Go project. |
| metadata | {"author":"go-ultimate-skill","version":"0.4.1","sources":["teetsh-org/claude-skills#golang-code-review","JetBrains/go-modern-guidelines#use-modern-go","powerman/skills#go-bounded-context-hexagonal","powerman/skills#go-engineering-policy","cloudwego/eino#orchestration-design-principles","cloudwego/eino#adk-0.1","modelcontextprotocol/go-sdk#design","philschmid.de#mcp-best-practices","modelcontextprotocol.info#docs/best-practices"],"source-notes":{"danicat-skills-deleted":"Originally also sourced from danicat/skills#go-best-practices and\ndanicat/skills#go-project-setup; both skills were deleted upstream on\n2026-07-21 (commit 201fa420, \"skill optimisation and repo cleanup\"). Their\ndistilled content is now owned and maintained by go-ultimate — the\nproject-setup boilerplates live under assets/ (verified to build with\nGo 1.26.x) and the best-practices material is folded into\nreferences/engineering-policy.md and references/code-review.md.\n","cloudwego-eino-adk-0.1":"`adk-0.1` is an in-repo ADK package, not a versioned tag; treated as a\npoint-in-time reference, not a recoverable pin.\n"}} |
Go Ultimate Skill
A single, opinionated skill for writing the best Go programs — synthesized from
four general-Go skills plus five agent/MCP donors. The full reasoning behind
every opinion (consensus, conflicts, resolutions) lives in
../skills-analysis.md.
When this skill applies
Always, for any Go work: code generation, refactoring, code review,
architecture and style discussions, scaffolding, or any change to .go files.
It overrides generic Go style/lint guidance when they conflict.
Setup — resolving <skill-dir>
Several instructions in this skill reference <skill-dir> — the absolute path to
this installed skill directory. Resolve it once per session, per the host
harness:
| Harness | Skill location |
|---|
| ZCode | ~/.zcode/skills/go-ultimate |
| Claude Code | ~/.claude/skills/go-ultimate |
| Cursor | ~/.cursor/skills/go-ultimate (or the workspace .cursor/skills/) |
| Codex CLI / OpenCode | the configured skills directory |
| Repo-local | <repo>/.claude/skills/go-ultimate (or equivalent) |
If unsure, locate the directory containing this SKILL.md and use its parent.
The bundled detector is at <skill-dir>/scripts/goversion/main.go; the
templates are at <skill-dir>/assets/.
How to use this skill
- Detect the project's Go version by running the bundled detector
go run <skill-dir>/scripts/goversion/main.go <project-path> (it prints the
bare version, e.g. 1.24.3, and always exits 0 — falling back to the Go
runtime version if no go.mod or no go directive is found). Use features
up to that version. See references/modern-go.md.
- Identify the project type using the decision tree below, then load the
matching reference.
- Follow the non-negotiable principles below — these always apply.
- On conflicts between references, apply the precedence rules at the end.
Project-type decision tree
Ask "what is the user building?" and route accordingly:
Is the code a single binary that the user runs?
├── Yes → Is it < ~300 lines with no external deps beyond stdlib?
│ ├── Yes → SCRIPT / TINY TOOL
│ │ → references/project-layouts.md § Scripts
│ │ → references/engineering-policy.md
│ └── No → CLI APPLICATION
│ → references/project-layouts.md § CLI
│ → references/engineering-policy.md
│
Is the code meant to be imported by other modules?
├── Yes → LIBRARY / MODULE
│ → references/libraries.md
│ → references/project-layouts.md § Library
│ → references/engineering-policy.md
│
Is the code a long-running server (HTTP/gRPC/messaging)?
├── Yes → BACKEND SERVICE
│ → references/architecture.md (mandatory)
│ → references/project-layouts.md § Service
│ → references/engineering-policy.md
│
Is the code a server exposing tools/resources/prompts to LLMs over MCP?
├── Yes → MCP SERVER
│ → references/mcp-server.md (mandatory)
│ → references/project-layouts.md § Service or § CLI (stdio server = CLI-shaped)
│ → references/engineering-policy.md
│
Is the code an LLM-driven agent that calls tools / orchestrates multi-step reasoning?
├── Yes → AI AGENT
│ → references/agents.md (mandatory)
│ → references/project-layouts.md § CLI or § Service (depends on hosting)
│ → references/engineering-policy.md
│
Is the code a code generator, linter, or analysis tool?
├── Yes → Treat as CLI APPLICATION or LIBRARY (whichever fits the distribution),
│ then see references/engineering-policy.md § Code generation
│
Otherwise → ask the user to clarify before proposing structure.
Non-negotiable principles (always apply)
These are the consensus backbone. Every Go file this skill touches obeys them.
-
Modern Go, version-gated. Use every feature up to the project's go.mod
version. any over interface{}. errors.Is/As over ==. slices/maps/
cmp over hand-rolled loops. See references/modern-go.md.
-
No pkg/ directory. Ever. Library code lives at the module root;
importable apps expose a public port/ package. The pkg/ convention is a
kubernetes-era anti-pattern. See references/project-layouts.md.
-
internal/ for private code; cmd/<name>/ for multiple binaries; flat for
tiny tools. Start simple; grow deliberately.
-
Context first, errors explicit. func F(ctx context.Context, ...) (..., error).
Wrap with fmt.Errorf("...: %w", err). Never compare errors with ==.
-
Thin adapters, fat-free imports. Business-logic packages never import
net/http, os, or transport SDKs. Adapters only translate formats and
protocol shapes.
-
Concurrency hygiene. Every goroutine has an exit condition (Context or
WaitGroup). Use errgroup for parallel fan-out. Always test with -race.
-
Accept interfaces, return structs. Interfaces are defined at the point of
use, not the point of implementation. Small, single-method interfaces win.
-
Comments explain why, not what. Named, idiomatic, exported identifiers do
the rest.
-
Typed contracts at boundaries. MCP tool args and agent inter-node data
flow are typed structs (generics where the framework supports it), never
map[string]any as the universal contract. See
references/mcp-server.md and
references/agents.md.
Quick reference (top rules, with link to detail)
| Rule | Detail |
|---|
| Detect Go version, use features up to it | modern-go.md |
| Pick layout by project type | project-layouts.md |
| Service architecture: bounded-context hexagonal | architecture.md |
package main: thin, run(ctx, cfg) error pattern, no testable logic in main() | engineering-policy.md |
| Config: Resolvable Config Struct (not Functional Options) | engineering-policy.md |
if x := f(); cond only when init is the condition; else separate statement | engineering-policy.md |
Errors: sentinels via errors.Is, typed via errors.As, wrap with %w, aggregate with errors.Join | engineering-policy.md |
Tests: vanilla testing, package xxx_test, TestF_suffixCamelCase names | testing.md |
Mocks: go.uber.org/mock (gomock) default; testify-mocks only if already on testify | testing.md |
| Review: Critical / Important / Suggestion / Positive buckets, What-Why-How per issue | code-review.md |
Libraries: README (rationale + honest comparison + payoff-first quick start) vs doc.go (contracts) | libraries.md |
go.mod: apps latest, libraries latest-1 | engineering-policy.md |
Lint: golangci-lint + govet + go test -race mandatory in CI | engineering-policy.md |
MCP server: official go-sdk, typed tool handlers, two-channel errors, tool design as outcomes-not-operations | mcp-server.md |
AI agent: ReAct loop w/ bounded iterations, 6 topology archetypes, type-aligned composition (reject map[string]any between nodes) | agents.md |
Conflict precedence (which reference wins)
When two references seem to disagree:
- Layout / architecture / ports / wiring / modular monolith for services →
architecture.md wins.
- Version-gated syntax (whether a feature exists in this Go version) →
modern-go.md wins.
- Everything else (config, errors, testing, naming, linting, dependencies,
CI) → engineering-policy.md wins.
- Library public-API concerns (semver, deprecation, doc.go split) →
libraries.md wins for library projects.
- Code review output format → code-review.md wins.
- MCP servers in Go (SDK choice, tool-handler design, two-channel errors,
pagination, middleware) → mcp-server.md wins.
- AI agents in Go (ReAct loop, multi-agent topology, typed data flow
between nodes, state externalism) → agents.md wins.
The adapter carve-out (mcp-server.md § "Adapter
carve-out") refines rule 5 of the non-negotiable principles for MCP handlers
only: the handler package is an inbound adapter and may import mcp.*.
Project-file precedence (escalation rule)
When a project-level instruction file contradicts this skill, follow this
order, stopping at the first match:
- Explicit user instruction in the current turn — always wins. If the user
says "use Functional Options here," use them, even though the skill mandates
Resolvable Config Struct.
- Project
AGENTS.md / CLAUDE.md at the repo root — wins over this skill
for project-specific conventions. A project that legitimately needs pkg/
(e.g. a kubernetes-style repo) says so there.
- This skill — the default for any Go decision not addressed above.
- Generic Go style/lint guidance — lowest priority; this skill overrides it
on conflicts by design.
If (1) and (2) are silent and the skill's rule feels wrong for the project,
say so out loud before applying it — propose the deviation, name the rule it
contradicts, and let the user decide. Do not silently override the skill, and do
not silently apply it when a project file arguably contradicts it.
Verification
After applying this skill to a Go project, the project should pass:
go vet ./...
go build ./...
go test -race ./...
If any of these fail as a result of changes made under this skill, that is a
skill regression — surface it, do not paper over it. For new projects scaffolded
from assets/, the result should compile and test green before handing control
back to the user.
Evaluating the skill itself
Example prompts and expected behaviors for catching drift live in
evals/. Run them when the skill is updated. The full audit
(methodology, scores, recommendations) is in
../skill-audit-report.md.
This skill is highly opinionated. Do not relitigate these rules at runtime —
apply them, and note any project-specific deviation in the project's own
AGENTS.md / CLAUDE.md if one exists.
