# Go Project Setup

> Standardized setup for new Go (Golang) projects and services. Activate to ensure clean, idiomatic project structures (Standard Layout) and implement production-ready patterns (graceful shutdown, package separation) from day one.

- Skill: `googlecloudplatform/go-project-setup` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx skillmds@latest add googlecloudplatform/go-project-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/googlecloudplatform/go-project-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: GoogleCloudPlatform (https://skillmd.com/u/googlecloudplatform)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/googlecloudplatform/go-project-setup

---


# Go Project Setup

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

## Core Mandates
1.  **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).
2.  **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.
3.  **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
1.  **Create Directory**: `mkdir my-app`
2.  **Init Module**: `go mod init github.com/user/my-app`
3.  **Linting**: (Optional) Initialize `.golangci.yml` if the project requires rigorous style enforcement.
4.  **Apply Template**: Copy and adapt the files from the chosen template in `assets/`. Ensure module names are updated.
5.  **Verify**: Run `go mod tidy` and `go build ./...`.

## References
*   `references/project_layout.md`: Official Go Module Layout guide.