go-style-guide

Name: go-style-guide
Author: madflojo

35stars3forks

How to install go-style-guide?

madflojo/go-style-agent-skill/go-style-guide

$npx -y skills add madflojo/go-style-agent-skill --skill go-style-guide

Installs into the current project.

Summary

Provides Go (Golang) engineering guidance for designing packages, services, and CLIs. Use whenever the task involves Go implementation, refactors, code reviews, API design, package layout, interfaces, constructors/config, error handling, logging, dependency or framework selection

Files · 1

View on GitHub

SKILL.md

1	# Go (Golang) Style Guide Skill
2
3	This skill defines practical Go engineering conventions for humans, coding
4	agents, and production-ready systems.
5
6	Use this skill whenever you are working with Go: new code, refactors, reviews,
7	architecture decisions, package design, or test strategy.
8
9	---
10
11	## TL;DR
12
13	- Design for testability first; inject dependencies and keep logic pure.
14	- Prefer `Config` in -> concrete struct out; validate, default, and document
15	important runtime knobs.
16	- Errors are contracts: use sentinels for durable branching; wrap the rest with
17	`%w` or `errors.Join`.
18	- Keep packages reusable: no hidden globals, no default logging, no surprise
19	side effects.
20	- Prefer the standard library before adding dependencies; third-party packages
21	must earn their weight through meaningful, maintained, adopted abstraction.
22	- Coverage is a signal, not proof; test edge cases and misuse paths, not just
23	happy paths.
24	- Follow "accept interfaces, return structs"; consumers usually define
25	interfaces, shared contract packages are a special case.
26	- Keep `main.go` thin; follow existing repo layout conventions rather than
27	forcing one directory shape.
28	- Benchmark hot paths before claiming wins, and run concurrency code with
29	`-race`.
30	- Maintain contracts such as function signatures, config shape, error behavior,
31	and doc comments; they are as important as the code itself.
32
33	---
34
35	## House Style Disclaimer
36
37	This is intentionally opinionated. It favors consistency and long-term
38	maintainability over accommodating every Go style preference. If the target repo
39	has clear local conventions, those conventions usually win.
40
41	---
42
43	## Compatibility
44
45	Examples assume modern Go and use standard-library features such as
46	`errors.Join` and `log/slog`. Apply the guide within the constraints of the
47	target repository's supported Go version.
48
49	---
50
51	## Execution Protocol
52
53	Follow this workflow when using the skill for implementation work:
54
55	1. Inspect the repository first.
56	Read existing package layout, constructors, tests, and error conventions
57	before proposing new APIs or moving files.
58
59	2. Define the contract before coding.
60	Decide the package boundary, config shape, concrete return type, sentinel
61	errors, dependency seams, and context or shutdown expectations up front.
62
63	3. Write or update tests early when practical.
64	Start with table-driven unit tests, add fuzz tests for parsing or other
65	input-heavy code, and add benchmarks for performance-sensitive paths.
66
67	4. Implement the smallest maintainable change.
68	Follow the repository's existing layout, keep `main.go` thin, and avoid
69	introducing new abstractions without a clear boundary.
70
71	5. Run the finishing checks.
72	Format with `gofmt` (and `goimports` if the repo uses it), run the relevant
73	`go test` targets, run `go test -race` when concurrency is involved, and run
74	benchmarks when claiming performance improvements.
75
76	6. Verify the human-facing contract.
77	Make sure docs, comments, config defaults, and error behavior match the code
78	you are shipping.
79
80	---
81
82	## Quick Rules Table
83
84	\| Topic \| Rule \| Reference \|
85	\| --- \| --- \| --- \|
86	\| Testability \| Design for confidence, not coverage percentages; test edge and misuse cases \| `references/TESTING.md` \|
87	\| Constructors \| `Config` in -> concrete struct out; validate + default in `New`; use `Config.Validate()` when config logic grows \| `references/CONFIG.md` \|
88	\| Errors \| Use sentinels for durable branching; wrap with `%w` or `errors.Join`; keep `recover` at app boundaries \| `references/ERRORS.md` \|
89	\| Logging \| Packages do not log by default; hot-path logging is a performance decision \| `references/LOGGING.md` \|
90	\| Dependencies \| Standard library first; add third-party packages only when they provide meaningful, maintained value \| `references/LAYOUT.md` \|
91	\| Interfaces \| "Accept interfaces, return structs"; consumers usually define interfaces \| `references/INTERFACES.md` \|
92	\| Documentation \| Write idiomatic godoc and durable comments; never add agent-context comments \| `references/DOCUMENTATION.md` \|
93	\| Layout \| Keep packages shallow, avoid junk drawers, and follow repo conventions \| `references/LAYOUT.md` \|
94	\| Entry Points \| `main.go` is wiring only \| `references/LAYOUT.md` \|
95	\| Benchmarks \| Benchmark hot paths; use `b.ReportAllocs()` and compare runs with `benchstat` \| `references/BENCHMARKS.md` \|
96	\| Testing \| Table-driven, stdlib-first, defensive against misuse, and fuzz-heavy where inputs are complex \| `references/TESTING.md` \|
97	\| C

People who liked this also viewed

6 picks

Type

go-style-guide

35stars3forks

View on GitHub

How to install go-style-guide?

madflojo/go-style-agent-skill/go-style-guide

$npx -y skills add madflojo/go-style-agent-skill --skill go-style-guide

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Go (Golang) Style Guide Skill
2
3	This skill defines practical Go engineering conventions for humans, coding
4	agents, and production-ready systems.
5
6	Use this skill whenever you are working with Go: new code, refactors, reviews,
7	architecture decisions, package design, or test strategy.
8
9	---
10
11	## TL;DR
12
13	- Design for testability first; inject dependencies and keep logic pure.
14	- Prefer `Config` in -> concrete struct out; validate, default, and document
15	important runtime knobs.
16	- Errors are contracts: use sentinels for durable branching; wrap the rest with
17	`%w` or `errors.Join`.
18	- Keep packages reusable: no hidden globals, no default logging, no surprise
19	side effects.
20	- Prefer the standard library before adding dependencies; third-party packages
21	must earn their weight through meaningful, maintained, adopted abstraction.
22	- Coverage is a signal, not proof; test edge cases and misuse paths, not just
23	happy paths.
24	- Follow "accept interfaces, return structs"; consumers usually define
25	interfaces, shared contract packages are a special case.
26	- Keep `main.go` thin; follow existing repo layout conventions rather than
27	forcing one directory shape.
28	- Benchmark hot paths before claiming wins, and run concurrency code with
29	`-race`.
30	- Maintain contracts such as function signatures, config shape, error behavior,
31	and doc comments; they are as important as the code itself.
32
33	---
34
35	## House Style Disclaimer
36
37	This is intentionally opinionated. It favors consistency and long-term
38	maintainability over accommodating every Go style preference. If the target repo
39	has clear local conventions, those conventions usually win.
40
41	---
42
43	## Compatibility
44
45	Examples assume modern Go and use standard-library features such as
46	`errors.Join` and `log/slog`. Apply the guide within the constraints of the
47	target repository's supported Go version.
48
49	---
50
51	## Execution Protocol
52
53	Follow this workflow when using the skill for implementation work:
54
55	1. Inspect the repository first.
56	Read existing package layout, constructors, tests, and error conventions
57	before proposing new APIs or moving files.
58
59	2. Define the contract before coding.
60	Decide the package boundary, config shape, concrete return type, sentinel
61	errors, dependency seams, and context or shutdown expectations up front.
62
63	3. Write or update tests early when practical.
64	Start with table-driven unit tests, add fuzz tests for parsing or other
65	input-heavy code, and add benchmarks for performance-sensitive paths.
66
67	4. Implement the smallest maintainable change.
68	Follow the repository's existing layout, keep `main.go` thin, and avoid
69	introducing new abstractions without a clear boundary.
70
71	5. Run the finishing checks.
72	Format with `gofmt` (and `goimports` if the repo uses it), run the relevant
73	`go test` targets, run `go test -race` when concurrency is involved, and run
74	benchmarks when claiming performance improvements.
75
76	6. Verify the human-facing contract.
77	Make sure docs, comments, config defaults, and error behavior match the code
78	you are shipping.
79
80	---
81
82	## Quick Rules Table
83
84	\| Topic \| Rule \| Reference \|
85	\| --- \| --- \| --- \|
86	\| Testability \| Design for confidence, not coverage percentages; test edge and misuse cases \| `references/TESTING.md` \|
87	\| Constructors \| `Config` in -> concrete struct out; validate + default in `New`; use `Config.Validate()` when config logic grows \| `references/CONFIG.md` \|
88	\| Errors \| Use sentinels for durable branching; wrap with `%w` or `errors.Join`; keep `recover` at app boundaries \| `references/ERRORS.md` \|
89	\| Logging \| Packages do not log by default; hot-path logging is a performance decision \| `references/LOGGING.md` \|
90	\| Dependencies \| Standard library first; add third-party packages only when they provide meaningful, maintained value \| `references/LAYOUT.md` \|
91	\| Interfaces \| "Accept interfaces, return structs"; consumers usually define interfaces \| `references/INTERFACES.md` \|
92	\| Documentation \| Write idiomatic godoc and durable comments; never add agent-context comments \| `references/DOCUMENTATION.md` \|
93	\| Layout \| Keep packages shallow, avoid junk drawers, and follow repo conventions \| `references/LAYOUT.md` \|
94	\| Entry Points \| `main.go` is wiring only \| `references/LAYOUT.md` \|
95	\| Benchmarks \| Benchmark hot paths; use `b.ReportAllocs()` and compare runs with `benchstat` \| `references/BENCHMARKS.md` \|
96	\| Testing \| Table-driven, stdlib-first, defensive against misuse, and fuzz-heavy where inputs are complex \| `references/TESTING.md` \|
97	\| C

People who liked this also viewed

6 picks

Type