OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add cxuu/golang-skills --skill go-interfaces
Use when defining or implementing Go interfaces, designing abstractions, creating mockable boundaries for testing, or composing types through embedding. Also use when deciding whether to accept an interface or return a concrete type, or using type assertions or type switches, even if the user doesn't explicitly mention interfaces. Does not cover generics-based polymorphism (see go-generics).
npx skills add cxuu/golang-skills --skill go-interfaces
scripts/check-interface-compliance.sh - Run as a heuristic to find exported interfaces that may need compile-time assertions.scripts/check-interface-compliance.go - Implementation helper invoked by check-interface-compliance.sh; patch this when changing method-set analysis.references/EMBEDDING.md - Read when embedding interfaces or structs in public APIs.references/RECEIVER-TYPE.md - Read when pointer/value receivers affect interface satisfaction.Interfaces belong in the package that consumes values, not the package that implements them. Return concrete (usually pointer or struct) types from constructors so new methods can be added without refactoring.
Do not define interfaces before they are used. Without a realistic example of usage, it is too difficult to see whether an interface is even necessary.
If a type exists only to implement an interface with no exported methods beyond that interface, return the interface from constructors to hide the implementation:
Benefits: implementation can change without affecting callers, substituting algorithms requires only changing the constructor call.
Without checking, a failed assertion causes a runtime panic. Always use the comma-ok idiom to test safely:
To check if a value implements an interface:
It's idiomatic to reuse the variable name (t := t.(type)) — the variable has
the correct type in each case branch. When a case lists multiple types
(case int, int64:), the variable has the interface type.
Avoid embedding types in public structs — the inner type's full method set becomes part of your public API. Use unexported fields instead.
Use a blank identifier assignment to verify a type implements an interface at compile time:
This causes a compile error if *RawMessage doesn't implement json.Marshaler.
Use this pattern when:
Don't add these checks for every interface — only when no other static conversion would catch the error.
Validation: After defining interfaces or implementations, run
bash scripts/check-interface-compliance.shto verify all concrete types have compile-timevar _ I = (*T)(nil)checks.
If in doubt, use a pointer receiver. Don't mix receiver types on a single
type — if any method needs a pointer, use pointers for all methods. Use value
receivers only for small, immutable types (Point, time.Time) or basic types.
| Concept | Pattern | Notes |
|---|---|---|
| Consumer owns interface | Define interfaces where used | Not in the implementing package |
| Safe type assertion | v, ok := x.(Type) | Returns zero value + false |
| Type switch | switch v := x.(type) | Variable has correct type per case |
| Interface embedding | type RW interface { Reader; Writer } | Union of methods |
| Struct embedding | type S struct { *T } | Promotes T's methods |
| Interface check | var _ I = (*T)(nil) | Compile-time verification |
| Generality | Return interface from constructor | Hide implementation |
-er suffix convention) or choosing receiver nameserror interface, custom error types, or errors.As matching// Good: producer returns concrete type
package producer
type Thinger struct{ ... }
func (t Thinger) Thing() bool { ... }
func NewThinger() Thinger { return Thinger{ ... } }// Bad: producer defines and returns its own interface
package producer
type Thinger interface { Thing() bool }
type defaultThinger struct{ ... }
func NewThinger() Thinger { return defaultThinger{ ... } }func NewHash() hash.Hash32 {
return &myHash{} // unexported type
}str, ok := value.(string)
if ok {
fmt.Printf("string value is: %q\n", str)
}if _, ok := val.(json.Marshaler); ok {
fmt.Printf("value %v implements json.Marshaler\n", val)
}var _ json.Marshaler = (*RawMessage)(nil)