Go Project Setup

This skill guides the creation of clean, idiomatic Go project structures.

Core Mandates

• Standard Layout Only: Use the official Go project layout (cmd/ , internal/ ).

• NEVER create a pkg/ directory. (It is an anti-pattern common in Kubernetes but not idiomatic Go).

• Flat by Default: Start with a flat structure (all files in root) for simple apps. Only introduce cmd/ and internal/ when multiple binaries or private packages are needed.

• Modern Go: Ensure go.mod specifies the latest stable Go version (currently 1.24+).

Workflow

1. Determine Scope

Ask the user: "Is this a simple tool, a library, or a multi-service repo?"

2. Select and Use Template

MANDATORY: You MUST read and use the templates provided in the assets/ directory. They establish idiomatic patterns like graceful shutdown, run functions, and package separation.

• Simple CLI / Tool: assets/cli-simple . Flat structure.

• Cobra CLI: assets/cli-cobra . For complex CLI tools.

• Library: assets/library . Package in root, internal/ for hidden logic.

• Application / Service: assets/webservice .

• cmd/app-name/main.go : Entry point using the run function pattern.

• internal/ : Private application logic.

• MCP Server: assets/mcp-server .

• Game: assets/game . Using Ebitengine.

3. Initialize

• Create Directory: mkdir my-app

• Init Module: go mod init github.com/user/my-app

• Linting: (Optional) Initialize .golangci.yml if the project requires rigorous style enforcement.

• Apply Template: Copy and adapt the files from the chosen template in assets/ . Ensure module names are updated.

• Verify: Run go mod tidy and go build ./... .

References

• references/project_layout.md : Official Go Module Layout guide.