skills.rest
VerifiedOrganic
VerifiedOrganicCOMMUNITY
Explore all skills by this author →
GitHub

golang-project-layout

Guides Go project structure, directory layout, and workspace organization decisions.

1|Updated Jun 2, 2026
Search Tags:#golang#monorepo#code organization#directory structure#project layout#go modules#go workspace
One-click install
npx skills add https://github.com/VerifiedOrganic/onboard --skill golang-project-layout-verifiedorganic
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: golang-project-layout
Source: https://github.com/VerifiedOrganic/onboard/tree/main/.agents/skills/golang-project-layout
Command: npx skills add https://github.com/VerifiedOrganic/onboard --skill golang-project-layout-verifiedorganic

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? Starting or reorganizing a Go project often leads to inconsistent directory structures, misplaced business logic, and anti-patterns like src/ or utils/ folders. This Skill provides opinionated, convention-based guidance for structuring Go projects correctly from the start. ## Core Features & Use Cases - Architecture-First Workflow: Prompts the developer to choose a software architecture and dependency injection approach before imposing any structure, and right-sizes the layout to project scope. - Directory Layout Guidance: Covers cmd/, internal/, pkg/ conventions, module naming rules, library vs. application layouts, multi-binary cmd/ structures, and Go workspaces (go.work) for monorepos. - Ready-to-Use Templates: Ships a Makefile, .gitignore, and references for testing layout, Cobra+Viper configuration, and 12-Factor App conventions. - Use Case: You are starting a new Go microservice with an API server and a migration tool. The Skill asks about your architecture preference, then scaffolds cmd/server and cmd/migrate entry points, places business logic in internal/, and sets up module naming, linting, and test co-location conventions. ## Quick Start Ask the agent to set up the directory structure for a new Go project and answer its questions about architecture and dependency injection preferences.

Frequently Asked Questions about golang-project-layout

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

FAQPage Schema
How do I structure a new Go project directory layout?▼

Place all main packages under cmd/{name}/ with minimal logic, put private application code in internal/, and use pkg/ only for code intended for external consumers. Add a go.mod matching your repository URL, plus a Makefile, .gitignore, and .golangci.yml at the root.

What is the difference between internal and pkg directories in Go?▼

The internal/ directory holds private code that Go itself prevents external modules from importing, while pkg/ is for libraries genuinely useful to outside consumers. Business logic belongs in internal/ by default; only shared, reusable packages go in pkg/.

When should I use go.work workspaces in Go?▼

Use go.work when developing multiple related Go modules that import each other, such as a monorepo with separate modules, to avoid replace directives. Do not use workspaces for single-module projects or simple applications with only external dependencies.

Should a Go library use cmd and pkg directories?▼

No. Libraries place public API packages at the repository root level, use internal/ for private implementation details, and omit cmd/ unless shipping example binaries. The application layout with cmd/, internal/, and pkg/ is meant for services and tools, not libraries.

Why is putting business logic in cmd/main.go a problem?▼

The cmd/ directory should contain only minimal main.go files that parse flags, wire dependencies, and call Run(). Request parsing, database queries, and other business logic belong in internal/ or pkg/ so they remain testable and reusable across multiple binaries.

Where should Go test files and fixtures be placed?▼

Co-locate _test.go files in the same directory as the code they test, using either the same package for white-box tests or a _test package suffix for black-box tests. Store fixtures in a testdata/ directory, which Go tooling ignores during builds.

Related Skills

Explore More Software Engineering Skills→
WU-MAO-CHIAWU-MAO-CHIA

speckit-git-initialize

Initializes a Git repository with an initial commit in spec-kit projects.

Community
Basic
LuigiAPCPereiraLuigiAPCPereira

golang-cli

Enforce code quality checks and CLI best practices for Go applications using Cobra and Viper.

Community
Intermediate
kreuzberg-devkreuzberg-dev
836

Go 1.25+ Standards

Enforce Go 1.25+ coding standards for error handling, testing, and linting.

Official
Intermediate
sambersamber
2.9k

golang-project-layout

Identify and apply optimal Go project layouts for single-module and monorepo structures.

Community
Intermediate