go-project-layout

Organize Go projects with standard cmd, internal, and pkg directory structures.

1|2|Updated Nov 25, 2017
One-click install
npx skills add https://github.com/asarchami/dotfiles --skill go-project-layout-asarchami
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: go-project-layout
Source: https://github.com/asarchami/dotfiles/tree/main/dot_config/opencode/skills/go/go-project-layout
Command: npx skills add https://github.com/asarchami/dotfiles --skill go-project-layout-asarchami

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? Deciding where Go code should live is a recurring source of inconsistency: main packages scattered at the repo root, business logic mixed into entry points, and over-engineered folder hierarchies for small tools. This Skill provides a disciplined, scope-appropriate layout process for new and existing Go projects. ## Core Features & Use Cases - New project scaffolding: Choose the right structure for CLI tools, libraries, services, monorepos, and workspaces, with correct go.mod naming and thin cmd/ entry points. - Restructuring existing codebases: Relocate main packages under cmd/{name}/, separate internal/ from pkg/, and right-size abstraction layers to actual complexity. - Testing and workspace layout: Co-locate _test.go files, use testdata/ fixtures, and set up go.work for multi-module monorepos. - Use Case: You are starting a new Go microservice and need to decide the module path, directory tree, Makefile, linter config, and test placement before writing the first handler. ## Quick Start Ask the assistant to set up a standard Go project layout for a new CLI tool or restructure an existing repository so all main packages live under cmd/ with business logic in internal/.

Frequently Asked Questions about go-project-layout

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

FAQPage Schema
How do I structure a Go project with multiple binaries?

Place each main package in its own subdirectory under cmd/, such as cmd/server/, cmd/worker/, and cmd/migrate/. Each main.go stays minimal, parsing flags and wiring dependencies, while business logic lives in internal/ or pkg/.

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

The internal/ directory holds private code that the Go compiler prevents other modules from importing. The pkg/ directory is for public libraries genuinely useful to external consumers; most application code belongs in internal/.

How do I set up a Go workspace for a monorepo?

Run go work init at the repository root, then add each module with go work use ./path/to/module. The workspace resolves local module imports automatically, eliminating replace directives in individual go.mod files.

Where should Go test files and fixtures be placed?

Co-locate _test.go files in the same directory and package as the code they test. Store package-specific fixtures in a testdata/ subdirectory, which Go tooling ignores during builds, or use test/fixtures/ for shared data.

When should I avoid a layered Go project structure?

Small scripts and single-purpose tools should stay flat rather than adopting clean architecture or hexagonal layers. Add abstraction only when the project's actual complexity justifies it, and decide the architecture and DI approach before scaffolding.