An opinionated agent skill for designing, reviewing, and refactoring Go code.

This repository packages a reusable skill plus supporting reference material for Go engineering decisions around package design, constructors and config, interfaces, errors, logging, documentation, layout, and benchmarks.

The go-style-guide skill is a practical Go engineering guide for:

• new package and API design
• refactors and restructures
• code review
• testability and dependency injection decisions
• error and logging contracts
• performance-sensitive code that should be benchmarked

It is designed to be useful to both human engineers and coding agents.

This guide reflects personal preferences. It is not intended to be a universal or official Go style guide.

The goal is consistency, maintainability, and production readiness in real codebases. If your repository already has established conventions, those should still win.

• testability-first package design
• Config-driven constructors with explicit validation and defaults
• boundary-driven interfaces, following "accept interfaces, return structs"
• sentinel-first error contracts with preserved wrapping semantics
• application-owned logging instead of hidden package logging
• idiomatic godoc and durable comments for public and important internal code
• benchmarks for performance-sensitive code paths
• shallow, domain-oriented package layouts

skills/
  go-style-guide/
    SKILL.md
    references/
      BENCHMARKS.md
      CONFIG.md
      CONCURRENCY.md
      DOCUMENTATION.md
      ERRORS.md
      INTERFACES.md
      LAYOUT.md
      LOGGING.md
      REVIEW-CHECKLIST.md
      TESTING.md

• skills/go-style-guide/SKILL.md is the main skill prompt.
• skills/go-style-guide/references/ contains deeper reference material that the skill can rely on when needed.

Copy the skills/go-style-guide/ directory into either:

• your repository's .agents/skills/ directory
• your user-level ~/.agents/skills/ directory

Adapt the destination to your agent tool's skill-directory convention if it differs.

In both cases, the final path should end with:

.agents/skills/go-style-guide/SKILL.md

The directory name becomes the skill identifier, so the skill should remain named go-style-guide unless you intentionally want a different invocation name.

Example:

your-project/
  .agents/
    skills/
      go-style-guide/
        SKILL.md
        references/

Or install it globally:

~/.agents/
  skills/
    go-style-guide/
      SKILL.md
      references/

Once installed, invoke it using the mechanism your agent tool provides for running skills. The skill identifier is go-style-guide.

The skill files in this repository are already organized so they can be copied directly into .agents/skills/go-style-guide/.

The examples in this repository assume modern Go and use standard-library features such as errors.Join and log/slog. Go 1.21+ is a good baseline.

If you apply this guide to an older repository, adapt the recommendations to the Go version that repository actually supports.

The supporting documents are organized by topic and are intended for on-demand lookup. Agents should start with SKILL.md and read only the specific references/*.md files needed for the current task:

• Configuration + Constructors
• Interfaces + Implementations
• Error Handling
• Logging
• Documentation + Comments
• Layout
• Benchmarks
• Testing
• Concurrency
• Review Checklist

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

This project is licensed under Apache-2.0.