golang-project-layout

Set up idiomatic Go repository directory structures for projects.

4|Updated May 17, 2026

Search Tags:#testing #architecture #go #workspaces #project layout #cmd internal pkg #go module

Ready to run

npx skills add https://github.com/hellopoisonx/aim --skill golang-project-layout-hellopoisonx

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: golang-project-layout
Source: https://github.com/hellopoisonx/aim/tree/main/skills/golang-project-layout
Command: npx skills add https://github.com/hellopoisonx/aim --skill golang-project-layout-hellopoisonx

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and assets (resource) components.

What problem does it solve?

It helps you avoid chaotic or over-engineered Go directory layouts by choosing conventions that match your project type, scope, and intended public/private APIs.

Core Features & Use Cases

Project-type driven layout selection: Choose a structure for CLI tools, libraries, services, and monorepos/workspaces.
Go module & package naming rules: Ensure your go.mod module path and package directories follow consistent, idiomatic conventions.
Practical Go architecture guardrails: Keep cmd/ focused on wiring while placing business logic in internal/ or pkg/ appropriately.
Quality defaults: Cover essential root files (Makefile, .gitignore, golangci-lint config), testing conventions, and monorepo workspace guidance.

Quick Start

Create a layout for your new Go service repository by generating cmd/{service}/main.go, an internal/ package skeleton for private logic, and a root go.mod whose module path matches your GitHub URL.

Frequently Asked Questions about golang-project-layout

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

What is the standard Go project layout for a new service or CLI tool?▼

A standard Go project layout uses a root go.mod, a minimal cmd/ directory for wiring, and internal/ for private business logic, keeping test files co-located with their packages.

How do I structure a Go monorepo using workspaces?▼

To structure a Go monorepo, use Go workspaces to manage multiple modules, ensuring each module follows cmd/internal/pkg conventions and consistent module naming rules.

When should I use internal/ vs pkg/ in my Go module?▼

Use the internal/ directory for private application code you want restricted from external imports, and pkg/ for public libraries intended to be safely imported by other Go modules.

What's the best way to organize cmd/ directories in a Go repository?▼

The best way to organize cmd/ is keeping it focused on wiring-first organization, placing each executable in cmd/{service}/main.go and moving all business logic to internal/ or pkg/.

Does this Go architecture guidance include root configuration files like Makefile and golangci-lint?▼

Yes, the guidance covers essential root files including Makefile, .gitignore, and golangci-lint configuration to establish quality defaults for your Go repository structure.