golang-structs-interfaces
Skill1 starsChanged 5 months agoMITView on GitHub
Golang struct and interface design patterns — composition, embedding, type assertions, type switches, interface segregation, dependency injection via interfaces, struct field tags, and pointer vs value receivers. Use this skill when designing Go types, defining or implementing interfaces, embedding structs or interfaces, writing type assertions or type switches, adding struct field tags for JSON/YAML/DB serialization, or choosing between pointer and value receivers. Also use when the user asks about "accept interfaces, return structs", compile-time interface checks, or composing small interfaces into larger ones.
- Installs packages
14 other projects use a version of this, 6 of them edited.
Adopted by
Most recently taken up by
- aiproxer/aiproxertheir own version, first seen Nov 8, 2026
- TeddyAlbina/skillsword for word, first seen Nov 1, 2026
- samber/cc-skills-golangedited, first seen Nov 1, 2026
- poizoncoded/skillsword for word, first seen Nov 1, 2026
- klawisha012/agentsyncedited, first seen Oct 25, 2026
- jniltinho/llama-modelword for word, first seen Oct 15, 2026
Other versions14 projects use a version of this.
Word for word · 6
- alexastrum/skl★ 11100% same
- poizoncoded/skills★ 2100% same
- TeddyAlbina/skills★ 2100% same
- gccli/skills★ 0100% same
- guynhsichngeodiec/cc-skills-golang★ 0100% same
- jniltinho/llama-model★ 0100% same
Edited · 6
- samber/cc-skills-golang★ 3.9k77% same
- klawisha012/agentsync★ 1097% same
- tstapler/dotfiles★ 889% same
- tquangkhai98/browser-profiles-manager★ 599% same
- rockcookies/skills★ 195% same
- rzisso/golang-skills★ 077% same
Wrote their own version · 2
- aiproxer/aiproxer★ 24same name
- reagin/agent-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository42 other files it gives its agents.
- golang-benchmarkSkill
- golang-cliSkill
- golang-code-styleSkill
- golang-concurrencySkill
- golang-contextSkill
- golang-continuous-integrationSkill
- golang-databaseSkill
- golang-data-structuresSkill
- golang-dependency-injectionSkill
- golang-dependency-managementSkill
- golang-design-patternsSkill
- golang-documentationSkill
- golang-error-handlingSkill
- golang-google-wireSkill
- golang-graphqlSkill
- golang-grpcSkill
- golang-how-toSkill
- golang-lintSkill
- golang-modernizeSkill
- golang-namingSkill
- golang-observabilitySkill
- golang-performanceSkill
- golang-popular-librariesSkill
- golang-project-layoutSkill
- golang-safetySkill
- golang-samber-doSkill
- golang-samber-hotSkill
- golang-samber-loSkill
- golang-samber-moSkill
- golang-samber-oopsSkill
- golang-samber-roSkill
- golang-samber-slogSkill
- golang-securitySkill
- golang-spf13-cobraSkill
- golang-spf13-viperSkill
- golang-stay-updatedSkill
- golang-stretchr-testifySkill
- golang-swaggerSkill
- golang-testingSkill
- golang-troubleshootingSkill
- golang-uber-digSkill
- golang-uber-fxSkill
The file
We split this skill into the rules it gives an agent
5 rules. 1 is common, 4 are distinctive, and 0 are very specific to this project.
1
Common
Most of the 8 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 97
NEVER create interfaces prematurely — wait for 2+ implementations or a testability requirement.
- Common: line 165
Verify a type implements an interface at compile time with a blank identifier assignment.
- Distinctive: line 209
Check if a value supports additional capabilities without requiring them upfront:
- Distinctive: line 294
Use field tags for serialization control.
- Distinctive: line 351
Always pass these structs by pointer:
“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Persona: You are a Go type system designer. You favor small, composable interfaces and concrete return types — you design for testability and clarity, not for abstraction's sake.
Community default. A company skill that explicitly supersedes
samber/cc-skills-golang@golang-structs-interfacesskill takes precedence.
Go Structs & Interfaces
Interface Design Principles
Keep Interfaces Small
"The bigger the interface, the weaker the abstraction." — Go Proverbs
Interfaces SHOULD have 1-3 methods. Small interfaces are easier to implement, mock, and compose. If you need a larger contract, compose it from small interfaces:
→ See samber/cc-skills-golang@golang-naming skill for interface naming conventions (method + "-er" suffix, canonical names)
type Reader interface {
Read(p []byte) (n int, err error)
}
type Writer interface {
Write(p []byte) (n int, err error)
}
// Composed from small interfaces
type ReadWriter interface {
Reader
Writer
}Compose larger interfaces from smaller ones:
type ReadWriteCloser interface {
io.Reader
io.Writer
io.Closer
}Define Interfaces Where They're Consumed
Interfaces Belong to Consumers.
Interfaces MUST be defined where consumed, not where implemented. This keeps the consumer in control of the contract and avoids importing a package just for its interface.
// package notification — defines only what it needs
type Sender interface {
Send(to, body string) error
}
type Service struct {
sender Sender
}The email package exports a concrete Client struct — it doesn't need to know about Sender.
Accept Interfaces, Return Structs
Functions SHOULD accept interface parameters for flexibility and return concrete types for clarity. Callers get full access to the returned type's fields and methods; consumers upstream can still assign the result to an interface variable if needed.
// Good — accepts interface, returns concrete
func NewService(store UserStore) *Service { ... }
// BAD — NEVER return interfaces from constructors
func NewService(store UserStore) ServiceInterface { ... }Don't Create Interfaces Prematurely
"Don't design with interfaces, discover them."
NEVER create interfaces prematurely — wait for 2+ implementations or a testability requirement. Premature interfaces add indirection without value. Start with concrete types; extract an interface when a second consumer or a test mock demands it.
// Bad — premature interface with a single implementation
type UserRepository interface {
FindByID(ctx context.Context, id string) (*User, error)
}
type userRepository struct { db *sql.DB }
// Good — start concrete, extract an interface later when needed
type UserRepository struct { db *sql.DB }Make the Zero Value Useful
Design structs so they work without explicit initialization. A well-designed zero value reduces constructor boilerplate and prevents nil-related bugs:
// Good — zero value is ready to use
var buf bytes.Buffer
buf.WriteString("hello")
var mu sync.Mutex
mu.Lock()
// Bad — zero value is broken, requires constructor
type Registry struct {
items map[string]Item // nil map, panics on write
}
// Good — lazy initialization guards the zero value
func (r *Registry) Register(name string, item Item) {
if r.items == nil {
r.items = make(map[string]Item)
}
r.items[name] = item
}Avoid any / interface{} When a Specific Type Will Do
Since Go 1.18+, MUST prefer generics over any for type-safe operations. Use any only at true boundaries where the type is genuinely unknown (e.g., JSON decoding, reflection):
// Bad — loses type safety
func Contains(slice []any, target any) bool { ... }
// Good — generic, type-safe
func Contains[T comparable](slice []T, target T) bool { ... }Key Standard Library Interfaces
| Interface | Package | Method |
Reader | io | Read(p []byte) (n int, err error) |
Writer | io | Write(p []byte) (n int, err error) |
Closer | io | Close() error |
Stringer | fmt | String() string |
error | builtin | Error() string |
Handler | net/http | ServeHTTP(ResponseWriter, *Request) |
Marshaler | encoding/json | MarshalJSON() ([]byte, error) |
Unmarshaler | encoding/json | UnmarshalJSON([]byte) error |
Canonical method signatures MUST be honored — if your type has a String() method, it must match fmt.Stringer. Don't invent ToString() or ReadData().
Compile-Time Interface Check
Verify a type implements an interface at compile time with a blank identifier assignment. Place it near the type definition:
var _ io.ReadWriter = (*MyBuffer)(nil)This costs nothing at runtime. If MyBuffer ever stops satisfying io.ReadWriter, the build fails immediately.
Type Assertions & Type Switches
Safe Type Assertion
Type assertions MUST use the comma-ok form to avoid panics:
// Good — safe
s, ok := val.(string)
if !ok {
// handle
}
// Bad — panics if val is not a string
s := val.(string)Type Switch
Discover the dynamic type of an interface value:
switch v := val.(type) {
case string:
fmt.Println(v)
case int:
fmt.Println(v * 2)
case io.Reader:
io.Copy(os.Stdout, v)
default:
fmt.Printf("unexpected type %T\n", v)
}Optional Behavior with Type Assertions
Check if a value supports additional capabilities without requiring them upfront:
type Flusher interface {
Flush() error
}
func writeData(w io.Writer, data []byte) error {
if _, err := w.Write(data); err != nil {
return err
}
// Flush only if the writer supports it
if f, ok := w.(Flusher); ok {
return f.Flush()
}
return nil
}This pattern is used extensively in the standard library (e.g., http.Flusher, io.ReaderFrom).
Struct & Interface Embedding
Struct Embedding
Embedding promotes the inner type's methods and fields to the outer type — composition, not inheritance:
type Logger struct {
*slog.Logger
}
type Server struct {
Logger
addr string
}
// s.Info(...) works — promoted from slog.Logger through Logger
s := Server{Logger: Logger{slog.Default()}, addr: ":8080"}
s.Info("starting", "addr", s.addr)The receiver of promoted methods is the inner type, not the outer. The outer type can override by defining its own method with the same name.
When to Embed vs Named Field
| Use | When |
| Embed | You want to promote the full API of the inner type — the outer type "is a" enhanced version |
| Named field | You only need the inner type internally — the outer type "has a" dependency |
// Embed — Server exposes all http.Handler methods
type Server struct {
http.Handler
}
// Named field — Server uses the store but doesn't expose its methods
type Server struct {
store *DataStore
}Dependency Injection via Interfaces
Accept dependencies as interfaces in constructors. This decouples components and makes testing straightforward:
type UserStore interface {
FindByID(ctx context.Context, id string) (*User, error)
}
type UserService struct {
store UserStore
}
func NewUserService(store UserStore) *UserService {
return &UserService{store: store}
}In tests, pass a mock or stub that satisfies UserStore — no real database needed.
Struct Field Tags
Use field tags for serialization control. Exported fields in serialized structs MUST have field tags:
type Order struct {
ID string `json:"id" db:"id"`
UserID string `json:"user_id" db:"user_id"`
Total float64 `json:"total" db:"total"`
Items []Item `json:"items" db:"-"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
DeletedAt time.Time `json:"-" db:"deleted_at"`
Internal string `json:"-" db:"-"`
}| Directive | Meaning |
json:"name" | Field name in JSON output |
json:"name,omitempty" | Omit field if zero value |
json:"-" | Always exclude from JSON |
json:",string" | Encode number/bool as JSON string |
db:"column" | Database column mapping (sqlx, etc.) |
yaml:"name" | YAML field name |
xml:"name,attr" | XML attribute |
validate:"required" | Struct validation (go-playground/validator) |
Pointer vs Value Receivers
Use pointer (s *Server) | Use value (s Server) |
| Method modifies the receiver | Receiver is small and immutable |
Receiver contains sync.Mutex or similar | Receiver is a basic type (int, string) |
| Receiver is a large struct | Method is a read-only accessor |
| Consistency: if any method uses a pointer, all should | Map and function values (already reference types) |
Receiver type MUST be consistent across all methods of a type — if one method uses a pointer receiver, all methods should.
Preventing Struct Copies with noCopy
Some structs must never be copied after first use (e.g., those containing a mutex, a channel, or internal pointers). Embed a noCopy sentinel to make go vet catch accidental copies:
// noCopy may be added to structs which must not be copied after first use.
// See https://pkg.go.dev/sync#noCopy
type noCopy struct{}
func (*noCopy) Lock() {}
func (*noCopy) Unlock() {}
type ConnPool struct {
noCopy noCopy
mu sync.Mutex
conns []*Conn
}go vet reports an error if a ConnPool value is copied (passed by value, assigned, etc.). This is the same technique the standard library uses for sync.WaitGroup, sync.Mutex, strings.Builder, and others.
Always pass these structs by pointer:
// Good
func process(pool *ConnPool) { ... }
// Bad — go vet will flag this
func process(pool ConnPool) { ... }Cross-References
- → See
samber/cc-skills-golang@golang-namingskill for interface naming conventions (Reader, Closer, Stringer) - → See
samber/cc-skills-golang@golang-design-patternsskill for functional options, constructors, and builder patterns - → See
samber/cc-skills-golang@golang-dependency-injectionskill for DI patterns using interfaces - → See
samber/cc-skills-golang@golang-code-styleskill for value vs pointer function parameters (distinct from receivers)
Common Mistakes
| Mistake | Fix |
| Large interfaces (5+ methods) | Split into focused 1-3 method interfaces, compose if needed |
| Defining interfaces in the implementor package | Define where consumed |
| Returning interfaces from constructors | Return concrete types |
| Bare type assertions without comma-ok | Always use v, ok := x.(T) |
| Embedding when you only need a few methods | Use a named field and delegate explicitly |
| Missing field tags on serialized structs | Tag all exported fields in marshaled types |
| Mixing pointer and value receivers on a type | Pick one and be consistent |
| Forgetting compile-time interface check | Add var _ Interface = (*Type)(nil) |
Using ToString() instead of String() | Honor canonical method names |
| Premature interface with a single implementation | Start concrete, extract interface when needed |
| Nil map/slice in zero value struct | Use lazy initialization in methods |
Using any for type-safe operations | Use generics ([T comparable]) instead |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

