From golang-skills
Guides Go interface usage: defining/implementing, abstractions, mockable testing boundaries, embedding, accepting interfaces vs concrete returns, type assertions/switches. Includes compliance check script.
npx claudepluginhub cxuu/golang-skills --plugin golang-skillsThis skill is limited to using the following tools:
- **`scripts/check-interface-compliance.sh`** — Finds exported interfaces missing compile-time compliance checks (`var _ I = (*T)(nil)`). Run `bash scripts/check-interface-compliance.sh --help` for options.
Guides Go interface design patterns: consumer-side definition, accept-interfaces-return-structs, composition, implicit satisfaction, and pitfalls. For decoupling packages, defining contracts, reviewing usage, refactoring for testability.
Guides Go struct and interface design: composition, embedding, type assertions/switches, segregation, dependency injection, field tags, pointer/value receivers. Use for type design and interface implementation.
Designs, reviews, and audits Go interfaces using discovery-over-design principles. Flags oversized interfaces, wrong definition sites, premature abstractions, and usage smells.
Share bugs, ideas, or general feedback.
scripts/check-interface-compliance.sh — Finds exported interfaces missing compile-time compliance checks (var _ I = (*T)(nil)). Run bash scripts/check-interface-compliance.sh --help for options.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.
// Good: consumer defines the interface it needs
package consumer
type Thinger interface { Thing() bool }
func Foo(t Thinger) string { ... }
// 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{ ... } }
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:
func NewHash() hash.Hash32 {
return &myHash{} // unexported type
}
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:
str, ok := value.(string)
if ok {
fmt.Printf("string value is: %q\n", str)
}
To check if a value implements an interface:
if _, ok := val.(json.Marshaler); ok {
fmt.Printf("value %v implements json.Marshaler\n", val)
}
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.
Read references/EMBEDDING.md when using struct embedding for composition, overriding embedded methods, resolving name conflicts, applying the HandlerFunc adapter pattern, or deciding whether to embed in public API types.
Use a blank identifier assignment to verify a type implements an interface at compile time:
var _ json.Marshaler = (*RawMessage)(nil)
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.
Read references/RECEIVER-TYPE.md when deciding between pointer and value receivers for a new type, especially for types with sync primitives or large structs.
| 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 matchingvar _ I = (*T)(nil) satisfaction checks at API boundaries