{"id":"e5c16489-8d85-403c-a1b1-9a787ba5dcd4","shortId":"f5LZLv","kind":"skill","title":"golang-project-layout","tagline":"Provides a guide for setting up Golang project layouts and workspaces. Use this whenever starting a new Go project, organizing an existing codebase, setting up a monorepo with multiple packages, creating CLI tools with multiple main packages, or deciding on directory structure. A","description":"**Persona:** You are a Go project architect. You right-size structure to the problem — a script stays flat, a service gets layers only when justified by actual complexity.\n\n# Go Project Layout\n\n## Architecture Decision: Ask First\n\nWhen starting a new project, **ask the developer** what software architecture they prefer (clean architecture, hexagonal, DDD, flat structure, etc.). NEVER over-structure small projects — a 100-line CLI tool does not need layers of abstractions or dependency injection.\n\n→ See `samber/cc-skills-golang@golang-design-patterns` skill for detailed architecture guides with file trees and code examples.\n\n## Dependency Injection: Ask Next\n\nAfter settling on the architecture, **ask the developer** which dependency injection approach they want: manual constructor injection, or a DI library (samber/do, google/wire, uber-go/dig+fx), or none at all. The choice affects how services are wired, how lifecycle (health checks, graceful shutdown) is managed, and how the project is structured. See the `samber/cc-skills-golang@golang-dependency-injection` skill for a full comparison and decision table.\n\n## 12-Factor App\n\nFor applications (services, APIs, workers), follow [12-Factor App](https://12factor.net/) conventions: config via environment variables, logs to stdout, stateless processes, graceful shutdown, backing services as attached resources, and admin tasks as one-off commands (e.g., `cmd/migrate/`).\n\n## Quick Start: Choose Your Project Type\n\n| Project Type | Use When | Key Directories |\n| --- | --- | --- |\n| **CLI Tool** | Building a command-line application | `cmd/{name}/`, `internal/`, optional `pkg/` |\n| **Library** | Creating reusable code for others | `pkg/{name}/`, `internal/` for private code |\n| **Service** | HTTP API, microservice, or web app | `cmd/{service}/`, `internal/`, `api/`, `web/` |\n| **Monorepo** | Multiple related packages/modules | `go.work`, separate modules per package |\n| **Workspace** | Developing multiple local modules | `go.work`, replace directives |\n\n## Module Naming Conventions\n\n### Module Name (go.mod)\n\nYour module path in `go.mod` should:\n\n- **MUST match your repository URL**: `github.com/username/project-name`\n- **Use lowercase only**: `github.com/you/my-app` (not `MyApp`)\n- **Use hyphens for multi-word**: `user-auth` not `user_auth` or `userAuth`\n- **Be semantic**: Name should clearly express purpose\n\n**Examples:**\n\n```go\n// ✅ Good\nmodule github.com/jdoe/payment-processor\nmodule github.com/company/cli-tool\n\n// ❌ Bad\nmodule myproject\nmodule github.com/jdoe/MyProject\nmodule utils\n```\n\n### Package Naming\n\nPackages MUST be lowercase, singular, and match their directory name. → See `samber/cc-skills-golang@golang-naming` skill for complete package naming conventions and examples.\n\n## Directory Layout\n\nAll `main` packages must reside in `cmd/` with minimal logic — parse flags, wire dependencies, call `Run()`. Business logic belongs in `internal/` or `pkg/`. Use `internal/` for non-exported packages, `pkg/` only when code is useful to external consumers.\n\nSee [directory layout examples](references/directory-layouts.md) for universal, small project, and library layouts, plus common mistakes.\n\n## Essential Configuration Files\n\nEvery Go project should include at the root:\n\n- **Makefile** — build automation. See [Makefile template](assets/Makefile)\n- **.gitignore** — git ignore patterns. See [.gitignore template](assets/.gitignore)\n- **.golangci.yml** — linter config. See the `samber/cc-skills-golang@golang-lint` skill for the recommended configuration\n\nFor application configuration with Cobra + Viper, see [config reference](references/config.md).\n\n## Tests, Benchmarks, and Examples\n\nCo-locate `_test.go` files with the code they test. Use `testdata/` for fixtures. See [testing layout](references/testing-layout.md) for file naming, placement, and organization details.\n\n## Go Workspaces\n\nUse `go.work` when developing multiple related modules in a monorepo. See [workspaces](references/workspaces.md) for setup, structure, and commands.\n\n## Initialization Checklist\n\nWhen starting a new Go project:\n\n- [ ] **Ask the developer** their preferred software architecture (clean, hexagonal, DDD, flat, etc.)\n- [ ] **Ask the developer** their preferred DI approach — see `samber/cc-skills-golang@golang-dependency-injection` skill\n- [ ] Decide project type (CLI, library, service, monorepo)\n- [ ] Right-size the structure to the project scope\n- [ ] Choose module name (matches repo URL, lowercase, hyphens)\n- [ ] Run `go version` to detect the current go version\n- [ ] Run `go mod init github.com/user/project-name`\n- [ ] Create `cmd/{name}/main.go` for entry point\n- [ ] Create `internal/` for private code\n- [ ] Create `pkg/` only if you have public libraries\n- [ ] For monorepos: Initialize `go work` and add modules\n- [ ] Run `gofmt -s -w .` to ensure formatting\n- [ ] Add `.gitignore` with `/vendor/` and binary patterns\n\n## Related Skills\n\n→ See `samber/cc-skills-golang@golang-cli` skill for CLI tool structure and Cobra/Viper patterns. → See `samber/cc-skills-golang@golang-dependency-injection` skill for DI approach comparison and wiring. → See `samber/cc-skills-golang@golang-lint` skill for golangci-lint configuration. → See `samber/cc-skills-golang@golang-continuous-integration` skill for CI/CD pipeline setup. → See `samber/cc-skills-golang@golang-design-patterns` skill for architectural patterns.","tags":["golang","project","layout","skills","samber","agent","agent-skills","antigravity","claude","claude-code","code","codex"],"capabilities":["skill","source-samber","skill-golang-project-layout","topic-agent","topic-agent-skills","topic-antigravity","topic-claude","topic-claude-code","topic-code","topic-codex","topic-coding","topic-copilot","topic-cursor","topic-gemini","topic-gemini-cli-extension"],"categories":["cc-skills-golang"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/samber/cc-skills-golang/golang-project-layout","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add samber/cc-skills-golang","source_repo":"https://github.com/samber/cc-skills-golang","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 1725 github stars · SKILL.md body (5,413 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:53:01.960Z","embedding":null,"createdAt":"2026-04-18T20:32:19.560Z","updatedAt":"2026-05-18T18:53:01.960Z","lastSeenAt":"2026-05-18T18:53:01.960Z","tsv":"'/)':227 '/company/cli-tool':380 '/dig':171 '/jdoe/myproject':387 '/jdoe/payment-processor':376 '/main.go':647 '/user/project-name':643 '/username/project-name':340 '/vendor':682 '/you/my-app':346 '100':111 '12':213,222 '12factor.net':226 '12factor.net/)':225 'abstract':120 'actual':75 'add':670,679 'admin':246 'affect':179 'api':219,294,302 'app':215,224,298 'applic':217,274,512 'approach':156,596,710 'architect':54 'architectur':80,94,98,133,149,584,744 'ask':82,89,143,150,578,590 'assets/.gitignore':496 'assets/makefile':488 'attach':243 'auth':357,360 'autom':484 'back':240 'bad':381 'belong':435 'benchmark':522 'binari':684 'build':269,483 'busi':433 'call':431 'check':187 'checklist':571 'choic':178 'choos':257,620 'ci/cd':733 'clean':97,585 'clear':367 'cli':36,113,267,607,692,695 'cmd':275,299,423,645 'cmd/migrate':254 'co':526 'co-loc':525 'cobra':515 'cobra/viper':699 'code':139,283,291,450,532,655 'codebas':27 'command':252,272,569 'command-lin':271 'common':469 'comparison':209,711 'complet':409 'complex':76 'config':229,499,518 'configur':472,510,513,724 'constructor':160 'consum':455 'continu':729 'convent':228,323,412 'creat':35,281,644,651,656 'current':634 'ddd':100,587 'decid':43,604 'decis':81,211 'depend':122,141,154,203,430,601,705 'design':128,740 'detail':132,549 'detect':632 'develop':91,152,314,555,580,592 'di':164,595,709 'direct':320 'directori':45,266,400,415,457 'e.g':253 'ensur':677 'entri':649 'environ':231 'essenti':471 'etc':103,589 'everi':474 'exampl':140,370,414,459,524 'exist':26 'export':445 'express':368 'extern':454 'factor':214,223 'file':136,473,529,544 'first':83 'fixtur':538 'flag':428 'flat':66,101,588 'follow':221 'format':678 'full':208 'fx':172 'get':69 'git':490 'github.com':339,345,375,379,386,642 'github.com/company/cli-tool':378 'github.com/jdoe/myproject':385 'github.com/jdoe/payment-processor':374 'github.com/user/project-name':641 'github.com/username/project-name':338 'github.com/you/my-app':344 'gitignor':489,494,680 'go':22,52,77,170,371,475,550,576,629,635,638,667 'go.mod':326,331 'go.work':308,318,553 'gofmt':673 'golang':2,11,127,202,405,504,600,691,704,717,728,739 'golang-c':690 'golang-continuous-integr':727 'golang-dependency-inject':201,599,703 'golang-design-pattern':126,738 'golang-lint':503,716 'golang-nam':404 'golang-project-layout':1 'golangci':722 'golangci-lint':721 'golangci.yml':497 'good':372 'google/wire':167 'grace':188,238 'guid':7,134 'health':186 'hexagon':99,586 'http':293 'hyphen':350,627 'ignor':491 'includ':478 'init':640 'initi':570,666 'inject':123,142,155,161,204,602,706 'integr':730 'intern':277,288,301,437,441,652 'justifi':73 'key':265 'layer':70,118 'layout':4,13,79,416,458,467,541 'librari':165,280,466,608,663 'lifecycl':185 'line':112,273 'lint':505,718,723 'linter':498 'local':316 'locat':527 'log':233 'logic':426,434 'lowercas':342,395,626 'main':40,418 'makefil':482,486 'manag':191 'manual':159 'match':334,398,623 'microservic':295 'minim':425 'mistak':470 'mod':639 'modul':310,317,321,324,328,373,377,382,384,388,558,621,671 'monorepo':31,304,561,610,665 'multi':353 'multi-word':352 'multipl':33,39,305,315,556 'must':333,393,420 'myapp':348 'myproject':383 'name':276,287,322,325,365,391,401,406,411,545,622,646 'need':117 'never':104 'new':21,87,575 'next':144 'non':444 'non-export':443 'none':174 'one':250 'one-off':249 'option':278 'organ':24,548 'other':285 'over-structur':105 'packag':34,41,312,390,392,410,419,446 'packages/modules':307 'pars':427 'path':329 'pattern':129,492,685,700,741,745 'per':311 'persona':48 'pipelin':734 'pkg':279,286,439,447,657 'placement':546 'plus':468 'point':650 'prefer':96,582,594 'privat':290,654 'problem':62 'process':237 'project':3,12,23,53,78,88,109,195,259,261,464,476,577,605,618 'provid':5 'public':662 'purpos':369 'quick':255 'recommend':509 'refer':519 'references/config.md':520 'references/directory-layouts.md':460 'references/testing-layout.md':542 'references/workspaces.md':564 'relat':306,557,686 'replac':319 'repo':624 'repositori':336 'resid':421 'resourc':244 'reusabl':282 'right':57,612 'right-siz':56,611 'root':481 'run':432,628,637,672 'samber/cc-skills-golang':125,200,403,502,598,689,702,715,726,737 'samber/do':166 'scope':619 'script':64 'see':124,198,402,456,485,493,500,517,539,562,597,688,701,714,725,736 'semant':364 'separ':309 'servic':68,181,218,241,292,300,609 'set':9,28 'settl':146 'setup':566,735 'shutdown':189,239 'singular':396 'size':58,613 'skill':130,205,407,506,603,687,693,707,719,731,742 'skill-golang-project-layout' 'small':108,463 'softwar':93,583 'source-samber' 'start':19,85,256,573 'stateless':236 'stay':65 'stdout':235 'structur':46,59,102,107,197,567,615,697 'tabl':212 'task':247 'templat':487,495 'test':521,534,540 'test.go':528 'testdata':536 'tool':37,114,268,696 'topic-agent' 'topic-agent-skills' 'topic-antigravity' 'topic-claude' 'topic-claude-code' 'topic-code' 'topic-codex' 'topic-coding' 'topic-copilot' 'topic-cursor' 'topic-gemini' 'topic-gemini-cli-extension' 'tree':137 'type':260,262,606 'uber':169 'uber-go':168 'univers':462 'url':337,625 'use':16,263,341,349,440,452,535,552 'user':356,359 'user-auth':355 'userauth':362 'util':389 'variabl':232 'version':630,636 'via':230 'viper':516 'w':675 'want':158 'web':297,303 'whenev':18 'wire':183,429,713 'word':354 'work':668 'worker':220 'workspac':15,313,551,563","prices":[{"id":"d34f7bab-8cb4-4be6-882e-ca48b66990da","listingId":"e5c16489-8d85-403c-a1b1-9a787ba5dcd4","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"samber","category":"cc-skills-golang","install_from":"skills.sh"},"createdAt":"2026-04-18T20:32:19.560Z"}],"sources":[{"listingId":"e5c16489-8d85-403c-a1b1-9a787ba5dcd4","source":"github","sourceId":"samber/cc-skills-golang/golang-project-layout","sourceUrl":"https://github.com/samber/cc-skills-golang/tree/main/skills/golang-project-layout","isPrimary":false,"firstSeenAt":"2026-04-18T21:55:16.565Z","lastSeenAt":"2026-05-18T18:53:01.960Z"},{"listingId":"e5c16489-8d85-403c-a1b1-9a787ba5dcd4","source":"skills_sh","sourceId":"samber/cc-skills-golang/golang-project-layout","sourceUrl":"https://skills.sh/samber/cc-skills-golang/golang-project-layout","isPrimary":true,"firstSeenAt":"2026-04-18T20:32:19.560Z","lastSeenAt":"2026-05-07T22:40:27.385Z"}],"details":{"listingId":"e5c16489-8d85-403c-a1b1-9a787ba5dcd4","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"samber","slug":"golang-project-layout","github":{"repo":"samber/cc-skills-golang","stars":1725,"topics":["agent","agent-skills","ai","antigravity","claude","claude-code","code","codex","coding","copilot","cursor","gemini","gemini-cli-extension","openclaw","opencode","plugin","skills","skillsmp","vibe-coding"],"license":"mit","html_url":"https://github.com/samber/cc-skills-golang","pushed_at":"2026-05-18T17:36:00Z","description":"🧑‍🎨 A collection of Golang agentic skills that works","skill_md_sha":"d5e73836e8afbd22d17189055857f8d54aa80acc","skill_md_path":"skills/golang-project-layout/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/samber/cc-skills-golang/tree/main/skills/golang-project-layout"},"layout":"multi","source":"github","category":"cc-skills-golang","frontmatter":{"name":"golang-project-layout","license":"MIT","description":"Provides a guide for setting up Golang project layouts and workspaces. Use this whenever starting a new Go project, organizing an existing codebase, setting up a monorepo with multiple packages, creating CLI tools with multiple main packages, or deciding on directory structure. Apply this for any Go project initialization or restructuring work.","compatibility":"Designed for Claude Code or similar AI coding agents, and for projects using Golang."},"skills_sh_url":"https://skills.sh/samber/cc-skills-golang/golang-project-layout"},"updatedAt":"2026-05-18T18:53:01.960Z"}}