golang-project-layout

Provides a guide for setting up Golang project layouts and workspaces. Use when starting a new Go project, organizing an existing codebase, setting up a monorepo with multiple packages, creating CLI tools with multiple main packages, deciding between cmd/internal/pkg directory conventions, or discussing package restructuring, package splits, or module splits.

1,768stars113forksUpdated 5/21/2026

Documentation #project-layout #monorepo #documentation #golang #cli-tools #dependency-injection

Security Assessment

Safe(100/100)

Security Score100/100

About golang-project-layout

The golang-project-layout skill provides developers with a structured guide for organizing and initializing Go projects efficiently. It addresses common challenges in project setup, such as choosing an appropriate directory structure, managing multiple packages in monorepos, and setting up CLI tools or services with minimal overhead. By offering clear guidelines and decision points, this skill helps avoid over-engineering small projects while maintaining best practices for scalable applications.

The skill includes guidance on architecture decisions, dependency injection strategies, and adherence to 12-Factor App principles for applications like services, APIs, and workers. It outlines project-specific layouts for CLI tools, libraries, services, monorepos, and workspaces. Additionally, it emphasizes proper module naming in go.mod files, lowercase and singular package naming, and separation of internal versus external code through `internal/` and `pkg/` directories. It also links to additional skills and resources for in-depth architecture and naming conventions.

Targeted primarily at Go developers and architects, this skill is useful for both beginners starting a new project and experienced developers restructuring existing codebases. It supports projects compatible with Claude Code or similar AI coding agents and is designed for a wide range of Go applications, from simple scripts to complex microservices. By following its recommendations, users can achieve maintainable, scalable, and standardized Go projects across individual, team, or monorepo setups.

FAQ

How do I start using the golang-project-layout skill?

You can invoke the skill whenever you need guidance for initializing or restructuring a Go project. It provides step-by-step recommendations for architecture, dependency injection, and directory structure based on your project type.

Which Go projects are compatible with this skill?

The skill is compatible with any Go project, including CLI tools, libraries, services, monorepos, and workspaces. It is specifically designed for projects that can be used with Claude Code or similar AI coding agents.

Does the skill enforce a specific architecture or DI library?

No, it recommends asking the developer about their preferred architecture and dependency injection approach. Options include manual constructor injection, DI libraries such as samber/do, google/wire, uber-go/dig+fx, or no DI at all.

Are there requirements for using the skill?

Yes, you need the Go toolchain installed as the skill requires Go binaries to analyze and suggest project layouts.

Can this skill help with monorepos or multi-module projects?

Yes, it provides guidance on using go.work files and organizing multiple related modules, ensuring proper separation and replace directives for local development.