playbooks

home / skills / linehaul-ai / linehaulai-claude-marketplace / effective-go

effective-go skill

/plugins/golang-orchestrator/skills/effective-go

This skill helps you write idiomatic, clean Go code by applying Effective Go practices across writing, review, and refactoring.

npx playbooks add skill linehaul-ai/linehaulai-claude-marketplace --skill effective-go

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.5 KB
---
name: effective-go
description: "Apply Go best practices, idioms, and conventions from golang.org/doc/effective_go. Use when writing, reviewing, or refactoring Go code to ensure idiomatic, clean, and efficient implementations."
keywords: [go, best-practices, coding-standards, idioms]
disable-model-invocation: false
user-invocable: true
---

# Effective Go

Apply best practices and conventions from the official [Effective Go guide](https://go.dev/doc/effective_go) to write clean, idiomatic Go code.

## When to Apply

Use this skill automatically when:
- Writing new Go code
- Reviewing Go code
- Refactoring existing Go implementations

## Key Reminders

Follow the conventions and patterns documented at https://go.dev/doc/effective_go, with particular attention to:

- **Formatting**: Always use `gofmt` - this is non-negotiable
- **Naming**: No underscores, use MixedCaps for exported names, mixedCaps for unexported
- **Error handling**: Always check errors; return them, don't panic
- **Concurrency**: Share memory by communicating (use channels)
- **Interfaces**: Keep small (1-3 methods ideal); accept interfaces, return concrete types
- **Documentation**: Document all exported symbols, starting with the symbol name

## References

- Official Guide: https://go.dev/doc/effective_go
- Code Review Comments: https://go.dev/wiki/CodeReviewComments
- Standard Library: Use as reference for idiomatic patterns
- **Error Handling Reference**: See `references/error-handling.md` for comprehensive error handling patterns (wrapping, sentinel errors, custom types, testing)

Overview

This skill applies Go best practices, idioms, and conventions from the Effective Go guide to help you write, review, and refactor Go code. It focuses on idiomatic style, correct error handling, clear naming, and concurrency patterns to produce readable, maintainable code. Use it to enforce consistency with the Go ecosystem and standard library practices.

How this skill works

The skill inspects Go source for common issues: formatting, naming, exported symbol documentation, interface design, error handling, and concurrency patterns. It recommends fixes—e.g., run gofmt, rename identifiers to MixedCaps, document exported functions, simplify interfaces, and prefer channel-based coordination when appropriate. It also points to standard library examples and Effective Go guidance for subtle cases.

When to use it

  • Writing new Go packages, libraries, or programs
  • Performing code reviews or pull request checks
  • Refactoring code to improve readability and maintainability
  • Teaching Go idioms to newer team members
  • Preparing code for public release or contribution to open source

Best practices

  • Always format code with gofmt before committing
  • Use MixedCaps for exported names and mixedCaps for unexported; avoid underscores
  • Document every exported type, function, and variable, starting the comment with the symbol name
  • Handle errors explicitly: check, wrap where useful, and return instead of panicking in library code
  • Design small interfaces (ideally 1–3 methods); accept interfaces and return concrete types when it simplifies callers
  • Favor communicating over shared memory for concurrency; use channels and goroutines idiomatically

Example use cases

  • Automated review checklist for pull requests that flags formatting, naming, and missing documentation
  • Refactor a large package to replace exported panics with returned errors and clear error wrapping
  • Rewrite concurrent components to use channels for coordination and reduce mutex complexity
  • Audit public APIs to ensure exported names, comments, and interface sizes follow idiomatic patterns
  • Educate developers by annotating code with Effective Go references and example-based suggestions

FAQ

Should I always avoid panic in Go?

Prefer returning errors in library code. Use panic for unrecoverable situations or when writing tests. Document behavior clearly if a function may panic.

When should I introduce an interface?

Introduce an interface when multiple implementations are expected or to simplify testing. Keep interfaces small and focused; prefer defining them at call sites when practical.