skills.rest
LuminaVault
LuminaVaultOFFICIAL
Explore all skills by this author →
GitHub

golang-project-layout

Guides Go project structure, module naming, and workspace setup using standard directory conventions.

Updated May 9, 2026
Search Tags:#scaffolding#golang#monorepo#directory structure#project layout#go modules#go workspace
One-click install
npx skills add https://github.com/LuminaVault/LuminaVaultShared --skill golang-project-layout-luminavault
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: golang-project-layout
Source: https://github.com/LuminaVault/LuminaVaultShared/tree/main/.agents/skills/golang-project-layout
Command: npx skills add https://github.com/LuminaVault/LuminaVaultShared --skill golang-project-layout-luminavault

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 in main packages, and confusion over cmd/, internal/, and pkg/ conventions. This Skill provides opinionated, community-standard guidance so Go projects are structured correctly from the start. ## Core Features & Use Cases - Project Type Layouts: Provides directory templates for CLI tools, libraries, services, and monorepos, with clear rules for cmd/, internal/, and pkg/ placement. - Module & Package Naming: Enforces Go module naming conventions (repo URL matching, lowercase, hyphens) and rejects anti-patterns like src/, utils/, helpers/, and common/. - Workspaces & Testing Layout: Covers go.work setup for multi-module monorepos and test file co-location with testdata/ fixture patterns. - Use Case: When scaffolding a new Go microservice, the Skill asks about architecture and DI preferences first, then generates a right-sized structure with cmd/server/, internal/, a Makefile, .gitignore, and 12-Factor config guidance. ## Quick Start Ask the agent to set up the directory structure for a new Go project, specifying whether it is a CLI tool, library, service, or monorepo.

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?▼

Place all main packages in cmd/{name}/ with minimal logic, put private application code in internal/, and use pkg/ only for code intended for external consumers. Add a Makefile, .gitignore, and .golangci.yml at the root, and right-size the structure to the project's actual complexity.

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

internal/ holds private code that Go's compiler prevents external modules from importing, while pkg/ is for libraries genuinely useful to outside consumers. Business logic and service code belong in internal/ by default; only shared libraries like a reusable logger 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 per service. Do not use workspaces for single-module projects, even ones with many packages, since a single go.mod already covers that case.

Where should main.go go in a Go project?▼

Each main package goes in its own subdirectory under cmd/, such as cmd/server/main.go, and contains only minimal logic: parse flags, wire dependencies, and call Run(). Business logic like request parsing or database queries belongs in internal/ or pkg/, never in cmd/.

Should I put secrets in a Viper config.yaml file?▼

No. Sensitive values like database passwords, API keys, and JWT secrets must come from environment variables or a secret manager, never config files. Config files are acceptable only for non-sensitive values like ports and log levels, following 12-Factor App principles.

Where do Go test files and fixtures go?▼

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→
sandgardenhqsandgardenhq
130

go-project-layout

Standardize Go project and module structure with cmd, internal, and pkg conventions.

Official
Basic
tamago0224tamago0224

golang-continuous-integration

Configure GitHub Actions CI/CD pipelines for Go projects.

Community
Advanced
leksaleksa

golang-enterprise-patterns

...

Community
Intermediate
lmorchardlmorchard
3

go-cli-builder

Scaffold Go CLI projects with Cobra, Viper, SQLite, and GitHub Actions.

Community
Advanced