Go Style Guide Skill

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.

What this is

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.

Opinionated by design

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.

What it emphasizes

• 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
• standard-library-first dependency choices with third-party packages only when they add meaningful, well-maintained abstraction
• idiomatic godoc and durable comments for public and important internal code
• benchmarks for performance-sensitive code paths
• shallow, domain-oriented package layouts

Repository layout

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.

Installing the skill

You can install this skill with either GitHub CLI or the skills npm package.

Install with GitHub CLI:

gh skill install madflojo/go-style-agent-skill

Install with npm via npx:

npx skills add -g -y madflojo/go-style-agent-skill

Optional: pin the GitHub CLI install to a release tag or commit SHA when you want reproducible installs:

gh skill install madflojo/go-style-agent-skill@v1.0.0
gh skill install madflojo/go-style-agent-skill@<commit-sha>

Both commands install the skill into the appropriate user-level skill directory automatically.

If you prefer a manual install, 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.

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

Compatibility notes

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.

Reference documents

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

Contributing

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

License

This project is licensed under Apache-2.0.