go-core-idioms

Name: go-core-idioms
Author: fusengine

21stars3forks

How to install go-core-idioms?

fusengine/agents/go-core-idioms

$npx -y skills add fusengine/agents --skill go-core-idioms

Installs into the current project.

Summary

Use when: writing or reviewing idiomatic sequential Go — error handling (%w wrapping, errors.Join, errors.Is/As, errors.AsType), slog structured logging, generics, small consumer-side interfaces, naming/style, new(expr), go fix modernizers. Do NOT use for: goroutines/channels/err

Files · 1

View on GitHub

SKILL.md

1	# Go Core Idioms
2
3	Idiomatic sequential Go for 1.26. For anything touching goroutines, channels,
4	`errgroup`, or `context` cancellation, use go-concurrency instead.
5
6	## Agent Workflow (MANDATORY)
7
8	Before ANY implementation, use `TeamCreate` to spawn 3 agents:
9
10	1. fuse-ai-pilot:explore-codebase - Map existing error/logging/interface patterns
11	2. fuse-ai-pilot:research-expert - Verify latest Go docs via Context7/Exa
12	3. mcp__context7__query-docs - Confirm stdlib signatures (errors, log/slog)
13
14	After implementation, run fuse-ai-pilot:sniper for validation.
15
16	---
17
18	## Overview
19
20	\| Feature \| Description \|
21	\|---------\|-------------\|
22	\| Error handling \| Explicit `if err != nil`, `%w` wrapping, `errors.Join`, `errors.AsType` (1.26) \|
23	\| Structured logging \| `log/slog` stdlib — handlers, attrs, groups, `LogValuer` \|
24	\| Generics \| Type params, constraints, self-referential types (1.26) \|
25	\| Interfaces \| Small, consumer-side — "accept interfaces, return structs" \|
26	\| Modernizers \| `go fix` auto-applies dozens of idiom/API fixers (1.26) \|
27
28	---
29
30	## Critical Rules
31
32	1. Explicit `if err != nil` - No sugar exists; never discard with `_ = err`
33	2. Wrap with `%w`, not `%v` - Preserves the chain for `errors.Is`/`As`/`AsType`
34	3. Accept interfaces, return structs - Define interfaces where consumed, not where produced
35	4. Value receivers by default - Use pointer receivers only for mutation or large structs
36	5. Run `go fix` + `go vet` - Let modernizers migrate to current idioms (1.26)
37
38	---
39
40	## Architecture
41
42	```
43	internal/
44	├── user/
45	│ ├── user.go # struct + value-receiver methods
46	│ ├── errors.go # sentinel + typed errors
47	│ └── repository.go # consumer-side interface, concrete struct returned
48	└── platform/
49	└── logging/
50	└── logger.go # slog setup, one *slog.Logger injected downward
51	```
52
53	→ See [error-patterns.md](references/templates/error-patterns.md) for full example
54
55	---
56
57	## Reference Guide
58
59	### Concepts
60
61	\| Topic \| Reference \| When to Consult \|
62	\|-------\|-----------\|-----------------\|
63	\| Error handling \| [error-handling.md](references/error-handling.md) \| Wrapping, sentinels, `errors.Join`, `AsType` \|
64	\| Structured logging \| [slog-logging.md](references/slog-logging.md) \| Choosing handlers, attrs, groups, perf \|
65	\| Generics & 1.26 \| [generics-and-1.26.md](references/generics-and-1.26.md) \| Type params, self-ref types, `new(expr)` \|
66	\| Interfaces & style \| [interfaces-and-style.md](references/interfaces-and-style.md) \| Interface placement, naming, receivers \|
67
68	### Templates
69
70	\| Template \| When to Use \|
71	\|----------\|-------------\|
72	\| [error-patterns.md](references/templates/error-patterns.md) \| Building an error strategy for a package \|
73	\| [slog-setup.md](references/templates/slog-setup.md) \| Wiring a structured logger into an app \|
74
75	---
76
77	## Quick Reference
78
79	### Wrap and inspect errors
80
81	```go
82	if err != nil {
83	return fmt.Errorf("load user %d: %w", id, err) // %w keeps the chain
84	}
85	// 1.26: type-safe, generic replacement for errors.As
86	if pathErr, ok := errors.AsType[*fs.PathError](err); ok {
87	log.Printf("failed path: %s", pathErr.Path)
88	}
89	```
90
91	→ See [error-handling.md](references/error-handling.md)
92
93	### Structured logging with slog
94
95	```go
96	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
97	logger.Info("user created", "id", id, slog.Duration("took", elapsed))
98	```
99
100	→ See [slog-logging.md](references/slog-logging.md)
101
102	---
103
104	## Best Practices
105
106	### DO
107	- Keep interfaces one-to-three methods, named at the call site
108	- Add context on the way up with `%w`; check with `errors.Is`/`AsType`
109	- Use `slog.LogAttrs` on hot paths to avoid allocation
110	- Run `go fix` to adopt current APIs and idioms automatically (1.26)
111
112	### DON'T
113	- Swallow errors (`_ = err`) or return bare `err` when context helps
114	- Define interfaces next to their implementation "just in case"
115	- Reach for pointer receivers without a mutation or size reason
116	- Write Java-esque getters/setters or `IFoo` interface prefixes

People who liked this also viewed

6 picks

Type

go-core-idioms

21stars3forks

View on GitHub

How to install go-core-idioms?

fusengine/agents/go-core-idioms

$npx -y skills add fusengine/agents --skill go-core-idioms

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Go Core Idioms
2
3	Idiomatic sequential Go for 1.26. For anything touching goroutines, channels,
4	`errgroup`, or `context` cancellation, use go-concurrency instead.
5
6	## Agent Workflow (MANDATORY)
7
8	Before ANY implementation, use `TeamCreate` to spawn 3 agents:
9
10	1. fuse-ai-pilot:explore-codebase - Map existing error/logging/interface patterns
11	2. fuse-ai-pilot:research-expert - Verify latest Go docs via Context7/Exa
12	3. mcp__context7__query-docs - Confirm stdlib signatures (errors, log/slog)
13
14	After implementation, run fuse-ai-pilot:sniper for validation.
15
16	---
17
18	## Overview
19
20	\| Feature \| Description \|
21	\|---------\|-------------\|
22	\| Error handling \| Explicit `if err != nil`, `%w` wrapping, `errors.Join`, `errors.AsType` (1.26) \|
23	\| Structured logging \| `log/slog` stdlib — handlers, attrs, groups, `LogValuer` \|
24	\| Generics \| Type params, constraints, self-referential types (1.26) \|
25	\| Interfaces \| Small, consumer-side — "accept interfaces, return structs" \|
26	\| Modernizers \| `go fix` auto-applies dozens of idiom/API fixers (1.26) \|
27
28	---
29
30	## Critical Rules
31
32	1. Explicit `if err != nil` - No sugar exists; never discard with `_ = err`
33	2. Wrap with `%w`, not `%v` - Preserves the chain for `errors.Is`/`As`/`AsType`
34	3. Accept interfaces, return structs - Define interfaces where consumed, not where produced
35	4. Value receivers by default - Use pointer receivers only for mutation or large structs
36	5. Run `go fix` + `go vet` - Let modernizers migrate to current idioms (1.26)
37
38	---
39
40	## Architecture
41
42	```
43	internal/
44	├── user/
45	│ ├── user.go # struct + value-receiver methods
46	│ ├── errors.go # sentinel + typed errors
47	│ └── repository.go # consumer-side interface, concrete struct returned
48	└── platform/
49	└── logging/
50	└── logger.go # slog setup, one *slog.Logger injected downward
51	```
52
53	→ See [error-patterns.md](references/templates/error-patterns.md) for full example
54
55	---
56
57	## Reference Guide
58
59	### Concepts
60
61	\| Topic \| Reference \| When to Consult \|
62	\|-------\|-----------\|-----------------\|
63	\| Error handling \| [error-handling.md](references/error-handling.md) \| Wrapping, sentinels, `errors.Join`, `AsType` \|
64	\| Structured logging \| [slog-logging.md](references/slog-logging.md) \| Choosing handlers, attrs, groups, perf \|
65	\| Generics & 1.26 \| [generics-and-1.26.md](references/generics-and-1.26.md) \| Type params, self-ref types, `new(expr)` \|
66	\| Interfaces & style \| [interfaces-and-style.md](references/interfaces-and-style.md) \| Interface placement, naming, receivers \|
67
68	### Templates
69
70	\| Template \| When to Use \|
71	\|----------\|-------------\|
72	\| [error-patterns.md](references/templates/error-patterns.md) \| Building an error strategy for a package \|
73	\| [slog-setup.md](references/templates/slog-setup.md) \| Wiring a structured logger into an app \|
74
75	---
76
77	## Quick Reference
78
79	### Wrap and inspect errors
80
81	```go
82	if err != nil {
83	return fmt.Errorf("load user %d: %w", id, err) // %w keeps the chain
84	}
85	// 1.26: type-safe, generic replacement for errors.As
86	if pathErr, ok := errors.AsType[*fs.PathError](err); ok {
87	log.Printf("failed path: %s", pathErr.Path)
88	}
89	```
90
91	→ See [error-handling.md](references/error-handling.md)
92
93	### Structured logging with slog
94
95	```go
96	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
97	logger.Info("user created", "id", id, slog.Duration("took", elapsed))
98	```
99
100	→ See [slog-logging.md](references/slog-logging.md)
101
102	---
103
104	## Best Practices
105
106	### DO
107	- Keep interfaces one-to-three methods, named at the call site
108	- Add context on the way up with `%w`; check with `errors.Is`/`AsType`
109	- Use `slog.LogAttrs` on hot paths to avoid allocation
110	- Run `go fix` to adopt current APIs and idioms automatically (1.26)
111
112	### DON'T
113	- Swallow errors (`_ = err`) or return bare `err` when context helps
114	- Define interfaces next to their implementation "just in case"
115	- Reach for pointer receivers without a mutation or size reason
116	- Write Java-esque getters/setters or `IFoo` interface prefixes

People who liked this also viewed

6 picks

Type