cxuu/golang-skills

go-generics

Use when deciding whether to use Go generics, writing generic functions or types, choosing constraints, or picking between type aliases and type definitions.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/cxuu/golang-skills --skill go-generics

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Go Generics and Type Parameters

Compatibility: Generics require Go 1.18+.

Resource Routing

  • references/CONSTRAINTS.md - Read when composing constraints, using type sets, or choosing between generics and interfaces.

When to Use Generics

Start with concrete types. Generalize only when a second type appears.

Prefer Generics When

  • Multiple types share identical logic (sorting, filtering, map/reduce)
  • You would otherwise rely on any and excessive type switching
  • You are building a reusable data structure (concurrent-safe set, ordered map)

Avoid Generics When

  • Only one type is being instantiated in practice
  • Interfaces already model the shared behavior cleanly
  • The generic code is harder to read than the type-specific alternative
"Write code, don't design types." — Robert Griesemer and Ian Lance Taylor

Decision Flow

Do multiple types share identical logic?
├─ No  → Use concrete types
├─ Yes → Do they share a useful interface?
│        ├─ Yes → Use an interface
│        └─ No  → Use generics

Bad:

go
// Premature generics: only ever called with int
func Sum[T constraints.Integer | constraints.Float](vals []T) T {
    var total T
    for _, v := range vals {
        total += v
    }
    return total
}

Good:

go
func SumInts(vals []int) int {
    var total int
    for _, v := range vals {
        total += v
    }
    return total
}

Type Parameter Naming

NameTypical Use
TGeneral type parameter
KMap key type
VMap value type
EElement/item type

For complex constraints, a short descriptive name is acceptable:

go
func Marshal[Opts encoding.MarshalOptions](v any, opts Opts) ([]byte, error)

Type Aliases vs Type Definitions

Type aliases (type Old = new.Name) are rare — use only for package migration or gradual API refactoring.


Constraint Composition

Combine constraints with ~ (underlying type) and | (union):

go
type Numeric interface {
    ~int | ~int8 | ~int16 | ~int32 | ~int64 |
    ~float32 | ~float64
}

func Sum[T Numeric](vals []T) T {
    var total T
    for _, v := range vals {
        total += v
    }
    return total
}

Use the constraints package or cmp package (Go 1.21+) for standard constraints like cmp.Ordered instead of writing your own.


Common Pitfalls

Don't Wrap Standard Library Types

go
// Bad: generic wrapper adds complexity without value
type Set[T comparable] struct {
    m map[T]struct{}
}

// Better: use map[T]struct{} directly when the usage is simple
seen := map[string]struct{}{}

Generics justify their complexity when they eliminate duplication across multiple call sites. A single-use generic is just indirection.

Don't Use Generics for Interface Satisfaction

go
// Bad: T is only used to satisfy an interface — just use the interface
func Process[T io.Reader](r T) error { ... }

// Good: accept the interface directly
func Process(r io.Reader) error { ... }

Avoid Over-Constraining

go
// Bad: constraint is more restrictive than needed
func Contains[T interface{ ~int | ~string }](slice []T, target T) bool { ... }

// Good: comparable is sufficient
func Contains[T comparable](slice []T, target T) bool { ... }

Quick Reference

TopicGuidance
When to use genericsOnly when multiple types share identical logic and interfaces don't suffice
Starting pointWrite concrete code first; generalize later
NamingSingle uppercase letter (T, K, V, E)
Type aliasesSame type, alternate name; use only for migration
Constraint compositionUse ~ for underlying types, ` for unions; prefer cmp.Ordered` over custom
Common pitfallDon't genericize single-use code or when interfaces suffice

Related Skills

  • Interfaces vs generics: See go-interfaces when deciding whether an interface already models the shared behavior without generics
  • Type declarations: See go-declarations when defining new types, type aliases, or choosing between type definitions and aliases
  • Documenting generic APIs: See go-documentation when writing doc comments and runnable examples for generic functions
  • Naming type parameters: See go-naming when choosing names for type parameters or constraint interfaces
from this repository

More skills

All skills
cxuu
Community

go-code-review

Use when reviewing Go code or checking code against community style standards. Also use proactively before submitting a Go PR or when reviewing any Go code changes, even if the user doesn't explicitly request a style review. Does not cover language-specific syntax — delegates to specialized skills.

1h installs
2
GitHub stars
189
Updated
Jun 20
cxuu
Community

go-concurrency

Use when writing concurrent Go code — goroutines, channels, mutexes, or thread-safety guarantees. Also use when parallelizing work, fixing data races, or protecting shared state, even if the user doesn't explicitly mention concurrency primitives. Does not cover context.Context patterns (see go-context).

1h installs
2
GitHub stars
189
Updated
Jun 20
cxuu
Community

go-context

Use when working with context.Context in Go — placement in signatures, propagating cancellation and deadlines, and storing values in context vs parameters. Also use when cancelling long-running operations, setting timeouts, or passing request-scoped data, even if they don't mention context.Context directly. Does not cover goroutine lifecycle or sync primitives (see go-concurrency).

1h installs
2
GitHub stars
189
Updated
Jun 20
cxuu
Community

go-control-flow

Use when writing conditionals, loops, or switch statements in Go — including if with initialization, early returns, for loop forms, range, switch, type switches, and blank identifier patterns. Also use when writing a simple if/else or for loop, even if the user doesn't mention guard clauses or variable scoping. Does not cover error flow patterns (see go-error-handling).

1h installs
2
GitHub stars
189
Updated
Jun 20