HadiCherkaoui/golang

Go (Golang) Development Skill

This skill enforces structured, guideline-driven Go development following Google Go Style Guide, Uber Go Style Guide, Effective Go, and Go Wiki CodeReviewComments.

Mandatory Workflow

This skill MUST be invoked for ANY Go action, including:

• Creating new .go files (even minimal examples like Hello World)
• Modifying existing .go files (any change, no matter how small)
• Creating or modifying go.mod files
• Writing or modifying tests (*_test.go files)
• Reviewing, refactoring, or rewriting Go code

Which Sub-Skill to Load and When

Before writing or modifying Go code, load ONLY the sub-skill files that apply to the requested task, using segmented reading (offset and limit) when needed.

Sub-Skills and When They Apply

1. go-style-core/SKILL.md

Use in ALL Go tasks. This file defines:

• Core principles (clarity, simplicity, consistency)
• Formatting rules and gofmt requirements (non-negotiable)
• Code organization basics
• Foundational principles for any Go project

2. go-naming/SKILL.md

Use when:

• Creating new packages, functions, methods, or variables
• Defining exported/unexported identifiers (MixedCaps vs mixedCaps)
• Naming constants, interfaces, or structs
• Choosing receiver names

3. go-error-handling/SKILL.md

Use when:

• Writing functions that return errors
• Wrapping errors with context using fmt.Errorf with %w
• Defining sentinel errors or custom error types
• Deciding between error return values and panics
• Handling errors from function calls (never ignore with _)

4. go-concurrency/SKILL.md

Use when:

• Creating goroutines
• Using channels for goroutine communication
• Working with sync primitives (Mutex, WaitGroup, RWMutex, etc.)
• Designing concurrent data structures
• Managing goroutine lifecycles and preventing leaks

5. go-interfaces/SKILL.md

Use when:

• Defining new interfaces
• Implementing interfaces implicitly
• Using type assertions or type switches
• Designing for interface composition
• Deciding between interfaces and concrete types
• Understanding "accept interfaces, return concrete types"

6. go-context/SKILL.md

Use when:

• Writing functions that accept context
• Propagating cancellation signals through call stacks
• Setting deadlines or timeouts for operations
• Storing/requesting values in context
• Designing APIs with context support
• Understanding context as first parameter convention

7. go-testing/SKILL.md

Use when:

• Writing test files (*_test.go)
• Creating table-driven tests
• Using subtests or parallel tests
• Writing test helpers
• Mocking dependencies
• Understanding test naming conventions

8. go-packages/SKILL.md

Use when:

• Creating new packages
• Organizing package structure
• Managing imports (standard library first, then external)
• Avoiding util/common packages
• Deciding what to export vs keep internal
• Working with internal packages

9. go-performance/SKILL.md

Use when:

• Optimizing hot paths identified by profiling
• Managing memory allocations
• Working with strings efficiently (Builder vs concatenation)
• Pre-allocating slices/maps with capacity hints
• Converting between types efficiently
• Using sync.Pool for object reuse

10. go-data-structures/SKILL.md

Use when:

• Using slices or arrays
• Working with maps and their zero values
• Allocating with new() vs make() (understanding the difference)
• Printing formatted output
• Using iota for enumerated constants
• Understanding nil slices vs empty slices

11. go-functional-options/SKILL.md

Use when:

• Designing constructors with many optional parameters
• Creating APIs with optional configuration
• Building fluent interfaces
• Avoiding config structs with many zero values
• Implementing the functional options pattern

12. go-linting/SKILL.md

Use when:

• Setting up linting configuration (.golangci.yml)
• Configuring golangci-lint with recommended linters
• Running go vet or gofmt
• Understanding which linters to enable for your project
• CI/CD integration for automated linting

13. go-code-review/SKILL.md

Use when:

• Reviewing Go code for best practices
• Checking for common issues and anti-patterns
• Following CodeReviewComments from Go Wiki
• Pre-submit code quality checks
• Ensuring consistency across the codebase

14. go-control-flow/SKILL.md

Use when:

• Writing if statements with initialization (if err := ...; err != nil)
• Designing for loops and range loops
• Using switch statements and type switches
• Working with defer, panic, and recover
• Understanding error flow control patterns

15. go-documentation/SKILL.md

Use when:

• Writing package documentation comments
• Documenting exported functions and types
• Creating doc comments that follow godoc conventions
• Adding examples to documentation
• Understanding package comment requirements

16. go-defensive/SKILL.md

Use when:

• Verifying interface implementations at compile time
• Copying slices or maps to prevent mutation
• Handling time calculations correctly
• Using defer for resource cleanup
• Defensive programming patterns in Go

Coding Rules

1. Load the necessary sub-skill files BEFORE ANY GO CODE GENERATION.
2. Apply the required rules from the relevant sub-skills.
3. ALWAYS run gofmt - formatting is non-negotiable in Go.
4. Check errors explicitly - never ignore with _ (unless truly intentional).
5. Use MixedCaps naming - no underscores in Go.
6. Pass context as first parameter, never store in structs.
7. Use channels for goroutine communication, shared memory for sharing.
8. Comments must ALWAYS be written in American English, unless the user explicitly requests otherwise.
9. If the file is fully compliant, add a comment: // Go guideline compliant {date} where {date} is the guideline date or current date (format YYYY-MM-DD)

Quick Reference

Error Handling: Always check errors immediately, wrap with context using fmt.Errorf("...: %w", err)

Formatting: Run gofmt -l . - must be empty (non-negotiable)

Concurrency: Use channels for communication, sync.WaitGroup for coordination, never unsynchronized shared state

Context: First parameter func(ctx context.Context, ...), propagate down, never store in structs

Naming: MixedCaps for exported, mixedCaps for unexported, no underscores

Verification Checklist

Before marking work complete:

• [ ] gofmt -l . returns empty (all files formatted)
• [ ] go vet ./... clean (no warnings)
• [ ] go test ./... passes (all tests green)
• [ ] Error handling explicit (no silently ignored errors with _)
• [ ] Context propagated correctly (first param, not stored)
• [ ] Goroutines properly synchronized (no leaks)
• [ ] Naming follows MixedCaps convention
• [ ] Interfaces are small and focused (not fat interfaces)
• [ ] Comments in American English
• [ ] Documentation complete for exported items

Anti-Patterns (NEVER)

• ❌ Ignoring errors with _ (unless truly intentional)
• ❌ panic() in normal code paths (only for unrecoverable programmer errors)
• ❌ Unsynchronized shared state between goroutines (data races)
• ❌ Storing context in structs or global variables
• ❌ Global variables for mutable state
• ❌ Goroutine leaks (missing WaitGroup.Done() or channel receive)
• ❌ interface{} when specific type would work
• ❌ Empty interfaces without proper type assertions
• ❌ Complex one-liners that reduce clarity
• ❌ Underscores in names (except in import aliases)
• ❌ util or common packages (organize by purpose instead)
• ❌ Getters with "Get" prefix (use Name() not GetName())

---