go-agent-skills

REST and gRPC API design patterns for Go services. Covers HTTP handlers, middleware, routing, request/response patterns, versioning, pagination, graceful shutdown, and OpenAPI documentation. Use when designing APIs, writing HTTP handlers, implementing middleware, structuring REST endpoints, or setting up gRPC services. Trigger examples: "design API", "REST endpoints", "HTTP handler", "middleware pattern", "graceful shutdown", "gRPC service", "API versioning". Do NOT use for general architecture (use go-architecture-review) or concurrency in handlers (use go-concurrency-review).

Review Go project architecture: package structure, dependency direction, layering, separation of concerns, domain modeling, and module boundaries. Use when reviewing architecture, designing package layout, evaluating dependency graphs, or refactoring monoliths into modules. Trigger examples: "review architecture", "package structure", "project layout", "dependency direction", "clean architecture Go", "module boundaries". Do NOT use for code-level style (use go-coding-standards) or API endpoint design (use go-api-design).

Build command-line tools in Go: flag handling, subcommands, stdin/stdout discipline, exit codes, signal handling, and when Cobra/Viper earn their weight over the standard library. Use when: "build a CLI", "add a subcommand", "parse flags", "exit codes", "handle Ctrl+C", "cobra command", "read from stdin", "CLI UX". Do NOT use for: HTTP API design (use go-api-design), project scaffolding in general (use go-project-layout), or configuration of services (use go-architecture-review).

Dependency injection in Go: constructor injection, wiring in main, avoiding global state, and when frameworks (wire, fx, dig) earn their complexity. Use when: "dependency injection", "wire up dependencies", "inject this", "remove global state", "singleton in Go", "use google/wire", "uber fx", "make this testable". Do NOT use for: interface design principles (use go-interface-design), project directory structure (use go-project-layout), or test doubles and mocks (use go-test-quality).

Idiomatic Go design patterns: functional options, builder, factory, strategy, middleware chain, pub/sub, and other patterns adapted for Go's type system. Use when: "design pattern", "functional options", "builder pattern", "factory pattern", "strategy pattern", "middleware chain", "option pattern", "how to structure this". Do NOT use for: interface design principles (use go-interface-design), package layout (use go-architecture-review), or concurrency patterns (use go-concurrency-review).

gRPC services in Go beyond the basics: proto design, status codes and error details, interceptors, deadlines, streaming, health checks, and graceful shutdown. Use when: "gRPC service", "proto design", "gRPC error handling", "interceptor", "gRPC streaming", "gRPC deadline", "grpc health check", "gRPC status codes". Do NOT use for: REST/HTTP handler design (use go-api-design), protobuf-agnostic API layering (use go-architecture-review), or TLS hardening details (use go-security-audit).

Go interface design patterns: implicit interfaces, consumer-side definition, interface compliance verification, composition, the accept-interfaces-return-structs principle, and common pitfalls. Use when designing interfaces, decoupling packages, defining contracts, reviewing interface usage, or refactoring for testability. Trigger examples: "design interface", "accept interfaces return structs", "interface compliance", "consumer-side interface", "interface composition". Do NOT use for HTTP handler patterns (use go-api-design) or general code review (use go-code-review).

Scaffold new Go projects and services: directory structure, cmd/ and internal/ conventions, when to use a flat layout, module naming, and main package wiring. Use when: "new Go project", "scaffold a service", "create project structure", "start a Go module", "how do I organize a new service", "set up folder structure". Do NOT use for: reviewing an existing architecture (use go-architecture-review), dependency injection wiring details (use go-dependency-injection), or CI pipeline setup (use go-ci).

Comprehensive code review checklist for Go projects. Evaluates code quality, idiomatic patterns, error handling, naming, package structure, and test coverage. Use when reviewing Go code, PRs, or before merging changes. Trigger examples: "review this code", "check this PR", "code review", "review Go file". Do NOT use for security-specific audits (use go-security-audit) or performance-specific analysis (use go-performance-review).

Go coding standards and style conventions grounded in Effective Go, Go Code Review Comments, and production-proven idioms. Use when writing or reviewing Go code, enforcing naming conventions, import ordering, variable declarations, struct initialization, or formatting rules. Trigger examples: "check Go style", "fix formatting", "review naming", "Go conventions". Do NOT use for architecture decisions, concurrency patterns, or performance tuning — use go-architecture-review, go-concurrency-review, or go-performance-review instead.

Correct usage of context.Context in Go: propagation, cancellation, timeouts, deadlines, values, and common anti-patterns. Use when: "context usage", "context.Context", "context cancellation", "timeout", "context.WithTimeout", "context.WithCancel", "context values", "context propagation". Do NOT use for: concurrency patterns beyond context (use go-concurrency-review), HTTP middleware context (use go-api-design), or error handling (use go-error-handling).

Correct use of Go's built-in data structures: slices (nil vs empty, append semantics, aliasing, preallocation), maps (comma-ok, sets, iteration order), arrays, and choosing between them. Use when: "slice vs array", "nil slice", "empty slice", "preallocate", "map iteration", "use a set in Go", "slice aliasing", "append gotcha", "copy a slice", "sync.Map or mutex". Do NOT use for: protecting structures shared across goroutines (use go-concurrency-review), allocation profiling (use go-performance-review), or generic container design (use go-design-patterns).

Go documentation conventions: godoc comments, package docs, testable Example functions, deprecation notices, and doc links. Use when: "add godoc", "document this package", "write doc comments", "add examples to docs", "deprecate a function", "package documentation", "improve the docs". Do NOT use for: commit messages (use git-commit), README-level project guides (plain writing task), or code style rules (use go-coding-standards).

Go error handling patterns, wrapping, sentinel errors, custom error types, and the errors package. Grounded in Effective Go, Go Code Review Comments, and production-proven idioms. Use when implementing error handling, designing error types, debugging error chains, or reviewing error handling patterns. Trigger examples: "handle errors", "error wrapping", "custom error type", "sentinel errors", "errors.Is", "errors.As". Do NOT use for panic/recover patterns in middleware (use go-api-design) or test assertion errors (use go-test-quality).

Modernize Go code to use current language features and standard library additions. Covers generics, log/slog, errors.Join, slices/maps packages, range-over-func, and iterators introduced in Go 1.21-1.23+. Use when: "modernize", "update to modern Go", "use generics", "replace interface{}", "upgrade Go version", "slog", "errors.Join", "range over func", "iterators". Do NOT use for: general code style (use go-coding-standards), error handling philosophy (use go-error-handling), or logging architecture (use go-observability).

Database patterns for Go services: database/sql, connection management, transactions, migrations, query builders, and ORM usage (sqlc, GORM, ent). Use when: "database access", "SQL query", "connection pool", "transactions", "database migration", "sqlc", "GORM", "ent", "prepared statement", "repository pattern". Do NOT use for: in-memory data structures (use go-coding-standards), security aspects of SQL (use go-security-audit), or performance profiling of queries (use go-performance-review).

Review and implement safe concurrency patterns in Go: goroutines, channels, sync primitives, context propagation, and goroutine lifecycle management. Use when writing concurrent code, reviewing async patterns, checking thread safety, debugging race conditions, or designing producer/consumer pipelines. Trigger examples: "check thread safety", "review goroutines", "race condition", "channel patterns", "sync.Mutex", "context cancellation", "goroutine leak". Do NOT use for general code style (use go-coding-standards) or HTTP handler patterns (use go-api-design).

Structured logging, distributed tracing, metrics, and health checks for Go services. Covers slog, OpenTelemetry, Prometheus, and observability best practices. Use when: "add logging", "structured logs", "add tracing", "OpenTelemetry", "add metrics", "Prometheus", "observability", "instrument this code". Do NOT use for: performance profiling with pprof (use go-performance-review), error handling patterns (use go-error-handling), or health check endpoints (use go-api-design).

Detect performance anti-patterns and apply optimization techniques in Go. Covers allocations, string handling, slice/map preallocation, sync.Pool, benchmarking, and profiling with pprof. Use when checking performance, finding slow code, reducing allocations, profiling, or reviewing hot paths. Trigger examples: "check performance", "find slow code", "reduce allocations", "benchmark this", "profile", "optimize Go code". Do NOT use for concurrency correctness (use go-concurrency-review) or general code style (use go-coding-standards).

Security review for Go applications: input validation, SQL injection, authentication/authorization, secrets management, TLS, OWASP Top 10, and secure coding patterns. Use when performing security reviews, checking for vulnerabilities, hardening Go services, or reviewing auth implementations. Trigger examples: "security review", "check vulnerabilities", "OWASP", "SQL injection", "input validation", "secrets management", "auth review". Do NOT use for dependency CVE scanning (use go-dependency-audit) or concurrency safety (use go-concurrency-review).

Diagnose runtime problems in Go programs: panics and stack traces, deadlocks, goroutine leaks, memory leaks, OOM kills, race reports, and debugging with delve and pprof. Use when: "debug this panic", "read this stack trace", "deadlock", "memory leak", "goroutine count growing", "OOM", "program hangs", "race detector output", "use delve". Do NOT use for: optimizing code that works (use go-performance-review), writing new concurrent code (use go-concurrency-review), or failing test design (use go-test-quality).

Go testing patterns for production-grade code: subtests, test helpers, fixtures, golden files, httptest, testcontainers, property-based testing, and fuzz testing. Covers mocking strategies, test isolation, coverage analysis, and test design philosophy. Use when writing tests, improving coverage, reviewing test quality, setting up test infrastructure, or choosing a testing approach. Trigger examples: "add tests", "improve coverage", "write tests for this", "test helpers", "mock this dependency", "integration test", "fuzz test". Do NOT use for performance benchmarking methodology (use go-performance-review), security testing (use go-security-audit), or table-driven test patterns specifically (use go-test-table-driven).

Deep dive on table-driven tests in Go: when to use them, when to avoid them, struct design, subtest naming, advanced patterns like test matrices and shared setup, and refactoring bloated tables into clean ones. Use when writing table-driven tests, refactoring test tables, reviewing table test structure, or deciding whether table-driven is the right approach. Trigger examples: "table-driven test", "table test", "test cases struct", "test matrix", "parametrize tests", "data-driven test", "refactor test table". Do NOT use for general test strategy, mocking, golden files, or fuzz testing (use go-test-quality). Do NOT use for benchmarks (use go-performance-review).

Structured git commit messages following Conventional Commits format for Go projects. Generates well-scoped, atomic commits with clear descriptions. Use when committing changes, writing commit messages, preparing PRs, or reviewing commit history quality. Trigger examples: "commit these changes", "create commit", "commit message", "prepare PR", "squash commits". Do NOT use for changelog generation (use changelog-generator) or code review (use go-code-review).

Continuous integration for Go projects: GitHub Actions pipelines, caching, golangci-lint setup, test/coverage gates, vulnerability scanning, build matrices, and Makefile targets. Use when: "set up CI", "GitHub Actions for Go", "add lint to the pipeline", "CI is slow", "coverage gate", "build matrix", "write a Makefile", "run govulncheck in CI". Do NOT use for: commit message conventions (use git-commit), choosing or auditing dependencies (use go-dependency-audit), or writing the tests themselves (use go-test-quality).

Audit Go module dependencies: detect outdated packages, check for known vulnerabilities, review go.mod hygiene, identify unused or redundant deps, and evaluate dependency quality. Use when auditing dependencies, checking for CVEs, cleaning up go.mod, upgrading modules, or evaluating third-party packages. Trigger examples: "check dependencies", "audit deps", "go.mod review", "update modules", "vulnerability scan", "govulncheck". Do NOT use for code-level security issues (use go-security-audit) or architecture review (use go-architecture-review).

Safe refactoring workflow for Go: behavior-preserving steps, compiler-checked renames, extracting packages, breaking circular dependencies, and strangler migrations — always behind green tests. Use when: "refactor this", "rename across the codebase", "extract a package", "break this circular dependency", "split this god package", "migrate callers", "clean up without changing behavior". Do NOT use for: deciding the target architecture (use go-architecture-review), adopting new language features (use go-modernize), or performance rewrites (use go-performance-review).

Navigate and analyze Go codebases semantically with the toolchain instead of text search: gopls (references, implementations, call hierarchy, rename), go list for the dependency graph, and go doc for APIs. Use when: "find all callers", "who implements this interface", "where is this used", "trace the dependency graph", "explore this codebase", "find usages before changing", "map the module". Do NOT use for: performing the refactor itself (use go-refactoring), judging the architecture found (use go-architecture-review), or documentation writing (use go-documentation).