skills.rest
vanstinator
vanstinatorCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

golang-project-layout

Guide Go repository directory structures with cmd/, internal/, pkg/, and configs/ conventions.

Updated May 28, 2026
Search Tags:#go#workspaces#project layout#cmd internal pkg#go module#architecture conventions#testing layout
One-click install
npx skills add https://github.com/vanstinator/semantic-search --skill golang-project-layout-vanstinator
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: golang-project-layout
Source: https://github.com/vanstinator/semantic-search/tree/main/.agents/skills/golang-project-layout
Command: npx skills add https://github.com/vanstinator/semantic-search --skill golang-project-layout-vanstinator

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill prevents messy Go codebases by guiding you to choose the right project layout for the kind of application or library you are building, so code stays maintainable as it grows.

Core Features & Use Cases

  • Right-sized Go layouts: Select between CLI tools, libraries, services, monorepos, and workspaces based on scope and ownership boundaries.
  • Correct cmd/ conventions: Keep all main packages inside cmd/{name}/ with minimal wiring logic, while placing business logic in internal/ or pkg/ appropriately.
  • Go module and package naming rules: Ensure go.mod module paths match the repository URL and that packages are lowercase, singular, and aligned with directory names.
  • Practical starter checklist: Cover initialization steps including go mod init, gofmt, and adding standard root files like Makefile, .gitignore, and golangci-lint config.
  • Testing and fixtures guidance: Co-locate _test.go files with the code they test and use testdata/ for fixtures.

Quick Start

Ask an AI coding agent to organize your new Go project using the golang-project-layout Skill, tailored to your planned structure (CLI, service, or library) and constraints.

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 Go project to keep my codebase maintainable as it grows?▼

To structure a Go project correctly, separate code into cmd/ for main packages, internal/ for private business logic, and pkg/ for shared code. This project layout prevents messy codebases by enforcing clear ownership boundaries and dependency injection rules.

What is the correct way to organize Go module paths and package names?▼

Go module paths in go.mod must match the repository URL, and package names should be lowercase, singular, and aligned with their directory names. Following these module naming and package layout rules ensures safe import conventions across your project.

How do I set up a new Go repository with standard root files?▼

Set up a new Go repository by running go mod init, applying gofmt, and adding standard root files like Makefile, .gitignore, and golangci-lint config. This starter checklist covers initialization steps for building CLI tools, libraries, or services.

Where should I put test files and test fixtures in a Go workspace?▼

Co-locate _test.go files directly with the code they test and use a testdata/ directory for fixtures. This testing layout ensures tests are easy to find and run within your Go module structure.

When should I use internal/ versus pkg/ when structuring Go code?▼

Use internal/ for private business logic that should not be imported by external projects, and pkg/ for code safe to share across repositories. Deciding where shared versus private code lives depends on your architecture and ownership boundaries.

Does this Go project layout support monorepos with multiple modules?▼

Yes, this Go project layout supports structuring monorepos with multiple modules by using Go workspaces. It helps you choose right-sized directory conventions for CLI tools, libraries, and services within a single repository scope.

Related Skills

Explore More Software Engineering Skills→
ivklgnivklgn
11

update-golang-deps

Audit and update Go module dependencies with govulncheck and tiered upgrades.

Community
Intermediate
dashkandashkan
1

golang-project-layout

Organize Go repositories into idiomatic cmd/internal/pkg layouts with go.mod and go.work.

Community
Intermediate
JylhisJylhis
1

golang-lint

Configure and run golangci-lint to enforce Go code quality standards.

Community
Intermediate
tokioutokiou
1

golang-project-layout

Generate Go project directory layouts for commands, internal code, and modules.

Community
Intermediate