Skip to main content
skill CX Codex

go-code-review · existential-birds — Claude Code skill: Go code review, install

go-code-review — a Go review skill that reads go.mod first, then checks errors, goroutines, interfaces and cleanup, ranking each finding by severity.

Apache-2.0 206 installs ★ 89 updated 2026-09-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add existential-birds/beagle --skill go-code-review -a claude-code
Open on GitHub

What go-code-review does

It starts with go.mod. The skill records the go directive before giving advice, so recommendations match the language version in the repo: loop variable capture only matters before 1.22, slog arrives in 1.21, errors.Join in 1.20. Then it reads the full functions around each edit instead of the diff hunk alone.

Checklist blocks get picked per change: error handling, concurrency, interfaces and types, resources, naming. Each block points at a file under references/. Findings come back as [FILE:LINE] ISSUE_TITLE with a severity of Critical, Major, Minor or Informational.

Step four loads a sibling skill at ../review-verification-protocol/SKILL.md. Without that skill installed next to this one, the pre-report check cannot run and the review stops short. The skill also names patterns it deliberately leaves alone, such as an ignored error with a written reason or a //nolint with an explanation.

What it helps with

  • catch an unchecked error on a network call
  • spot a goroutine with no shutdown path
  • review loop variable capture in pre-1.22 code
  • sort findings by severity before merge
  • skip idiomatic patterns that only look wrong

Example prompts for the agent

  • Review internal/queue/worker.go; read go.mod first, then the whole function.
  • Check the goroutines and channels in this diff and rank the findings by severity.
  • Run the interface and generics checklist over the storage package.

How to install go-code-review

1Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill go-code-review -a claude-code

2Manually: put the files in place

~/.claude/skills/go-code-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/go-code-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about go-code-review

How do I install go-code-review in Claude Code?

Run npx skills add existential-birds/beagle --skill go-code-review -a claude-code. The skill lands at ~/.claude/skills/go-code-review/SKILL.md.

What does go-code-review do?

It reviews Go files against a checklist: error handling, concurrency, interfaces, resources, naming. Every finding gets a level from Critical down to Informational.

Does it need another skill to work?

Yes. Step four loads review-verification-protocol from ../review-verification-protocol/SKILL.md, so that skill has to sit next to it.

Source text

SKILL.md · Apache-2.0
---
name: go-code-review
description: Reviews Go code for idiomatic patterns, error handling, concurrency safety, and common mistakes. Use when reviewing .go files, checking error handling, goroutine usage, or interface design. Covers generics (Go 1.18+), errors.Join and slog (Go 1.21+), and Go 1.22 loop variable semantics.
---

# Go Code Review

## Review Workflow

Follow this sequence **in order**. Do not emit findings until every **Pass** below is satisfied.

1. **Baseline `go.mod`** — Open `go.mod` and read the `go` directive.  
   **Pass:** You can state the exact `go X.YY` value (in the review preamble or working notes). Apply version-gated advice only when it matches this baseline (loop capture pre-1.22, `slog`/structured logging from 1.21, `errors.Join` from 1.20).

2. **Read surrounding code** — For each changed `.go` file, read full functions or logical units that contain the edits, not only the diff hunk.  
   **Pass:** At least one full enclosing function (or package-level `init`/var block) containing the change was read per changed file.

3. **Scope the checklist** — Decide which [Review Checklist](#review-checklist) blocks apply (error handling, concurrency, interfaces/types, resources, naming). Load [references](#quick-reference) for those blocks; skip blocks that are irrelevant to the diff.  
   **Pass:** The review (or working notes) lists which checklist blocks you applied, or marks blocks N/A with a one-line reason tied to the diff (e.g. “no concurrency in change”).

4. **Pre-report verification** — Load and follow [review-verification-protocol](../review-verification-protocol/SKILL.md).  
   **Pass:** The protocol’s **Pre-Report Verification Checklist** is satisfied for each finding you will report (actual code read, surrounding context checked, “wrong” vs “different style” distinguished, etc.).

## Hard gates (same sequence, shorter)

| Step | Objective pass condition |
| --- | --- |
| 1 | `go X.YY` from `go.mod` is recorded before version-specific advice. |
| 2 | Full enclosing context read per changed file, not diff-only. |
| 3 | In-scope checklist blocks listed or N/A with diff-tied reason; references opened as needed. |
| 4 | `review-verification-protocol` completed for every reported issue. |

## Output Format

Report findings as:

```text
[FILE:LINE] ISSUE_TITLE
Severity: Critical | Major | Minor | Informational
Description of the issue and why it matters.
```

## Quick Reference

| Issue Type | Reference |
|------------|-----------|
| Missing error checks, wrapping, errors.Join | [references/error-handling.md](references/error-handling.md) |
| Race conditions, channel misuse, goroutine lifecycle | [references/concurrency.md](references/concurrency.md) |
| Interface pollution, naming, generics | [references/interfaces.md](references/interfaces.md) |
| Resource leaks, defer misuse, slog, naming | [references/common-mistakes.md](references/common-mistakes.md) |

## Review Checklist

### Error Handling
- [ ] All errors checked (no `_ = err` without justifying comment)
- [ ] Errors wrapped with context (`fmt.Errorf("...: %w", err)`)
- [ ] `errors.Is`/`errors.As` used instead of string matching
- [ ] `errors.Join` used for aggregating multiple errors (Go 1.20+)
- [ ] Zero values returned alongside errors

### Concurrency
- [ ] No goroutine leaks (context cancellation or shutdown signal exists)
- [ ] Channels closed by sender only, exactly once
- [ ] Shared state protected by mutex or sync types
- [ ] WaitGroups used to wait for goroutine completion
- [ ] Context propagated through call chain
- [ ] Loop variable capture handled (pre-Go 1.22 codebases only)

### Interfaces and Types
- [ ] Interfaces defined by consumers, not producers
- [ ] Interface names follow `-er` convention
- [ ] Interfaces minimal (1-3 methods)
- [ ] Concrete types returned from constructors
- [ ] `any` preferred over `interface{}` (Go 1.18+)
- [ ] Generics used where appropriate instead of `any` or code generation

### Resources and Lifecycle
- [ ] Resources closed with `defer` immediately after creation
- [ ] HTTP response bodies always closed
- [ ] No `defer` in loops without closure wrapping
- [ ] `init()` functions avoided in favor of explicit initialization

### Naming and Style
- [ ] Exported names have doc comments
- [ ] No stuttering names (`user.UserService` → `user.Service`)
- [ ] No naked returns in functions > 5 lines
- [ ] Context passed as first parameter
- [ ] `slog` used over `log` for structured logging (Go 1.21+)

## Severity Calibration

### Critical (Block Merge)
- Unchecked errors on I/O, network, or database operations
- Goroutine leaks (no shutdown path)
- Race conditions on shared state (concurrent map access without sync)
- Unbounded resource accumulation (defer in loop, unclosed connections)

### Major (Should Fix)
- Errors returned without context (bare `return err`)
- Missing WaitGroup for spawned goroutines
- `panic` for recoverable errors
- Context not propagated to downstream calls

### Minor (Consider Fixing)
- `interface{}` instead of `any` in Go 1.18+ codebases
- Missing doc comments on exports
- Stuttering names
- Slice not preallocated when size is known

### Informational (Note Only)
- Suggestions to add generics where code generation exists
- Refactoring ideas for interface design
- Performance optimizations without measured impact

## When to Load References

- Reviewing error return patterns → error-handling.md
- Reviewing goroutines, channels, or sync types → concurrency.md
- Reviewing type definitions, interfaces, or generics → interfaces.md
- General review (resources, naming, init, performance) → common-mistakes.md

## Valid Patterns (Do NOT Flag)

These are acceptable Go patterns — reporting them wastes developer time:

- **`_ = err` with reason comment** — Intentionally ignored errors with explanation
- **Empty interface / `any`** — For truly generic code or interop with untyped APIs
- **Naked returns in short functions** — Acceptable in functions < 5 lines with named returns
- **Channel without close** — When consumer stops via context cancellation, not channel close
- **Mutex protecting struct fields** — Even if accessed only via methods, this is correct encapsulation
- **`//nolint` directives with reason** — Acceptable when accompanied by explanation
- **Defer in loop** — When function scope cleanup is intentional (e.g., processing files in batches)
- **Functional options pattern** — `type Option func(*T)` with `With*` constructors is idiomatic
- **`sync.Pool` for hot paths** — Acceptable for reducing allocation pressure in performance-critical code
- **`context.Background()` in main/tests** — Valid root context for top-level calls
- **`select` with `default`** — Non-blocking channel operation, intentional pattern
- **Short variable names in small scope** — `i`, `err`, `ctx`, `ok` are idiomatic Go

## Context-Sensitive Rules

Only flag these issues when the specific conditions apply:

| Issue | Flag ONLY IF |
|-------|--------------|
| Missing error check | Error return is actionable (can retry, log, or propagate) |
| Goroutine leak | No context cancellation path exists for the goroutine |
| Missing defer | Resource isn't explicitly closed before next acquisition or return |
| Interface pollution | Interface has > 1 method AND only one consumer exists |
| Loop variable capture | `go.mod` specifies Go < 1.22 |
| Missing slog | `go.mod` specifies Go >= 1.21 AND code uses `log` package for structured output |

## Before Submitting Findings

Satisfy **step 4** in [Review Workflow](#review-workflow): load [review-verification-protocol](../review-verification-protocol/SKILL.md) and complete its pre-report checks for each issue.

© existential-birds · Apache-2.0 · existential-birds/beagle

Similar skills

All skills for Code review and refactoring →

go-code-review by other authors comes first.

go-code-review cxuu go-code-review is a skill for Claude Code that checks Go code against community style standards and reports findings by severity. Use it before opening a PR. CX Codex +1 1,800installs go-code-review eduardo-sl The go-code-review skill for Claude Code checks Go code and PRs against a structured checklist, catching issues before changes are merged. CX Codex +1 ★ 90repo stars go-concurrency-review eduardo-sl go-concurrency-review is a Claude Code skill for reviewing and implementing concurrency patterns in Go. It kicks in for goroutine reviews, race investigations, and producer-consumer pipeline design. CX Codex +1 ★ 90repo stars go PatrickJS This rule guides Cursor toward idiomatic Go with explicit errors, interface-based design, and context-aware concurrency. It targets .go files. CX Codex +1 ★ 41,178repo stars golang-patterns affaan-m The golang-patterns skill guides Go coding, reviews, and refactors with idiomatic patterns. Use it when package structure, errors, or concurrency need a closer check. CX Codex +1 7,200installs golang saisudhir14 golang — a skill that hands your agent Go production rules: error handling, concurrency, naming, testing, generics. Useful when you write or review Go in Claude. CX Codex +1 535installs go-context eduardo-sl go-context — a skill that makes your coding agent handle context.Context in Go correctly: cancellation, timeouts, values and the usual anti-patterns. CX Codex +1 ★ 90repo stars java-code-review decebals java-code-review — a skill that walks Java code through a checklist: null safety, exceptions, concurrency, resource leaks. Handy before you merge a PR. CX Codex +1 1,200installs

From the same set68

The whole set →
pydantic-ai-common-pitfalls pydantic-ai-common-pitfalls walks through the mistakes that break PydanticAI agents and gives a fixed order for debugging: tool decorators, deps, output schemas, streaming. CX Codex +1 221installs agent-architecture-analysis agent-architecture-analysis audits an LLM agent codebase against the 12-Factor Agents rubric, then scores each factor and points at the files behind the score. CX Codex +1 220installs pydantic-ai-agent-creation The pydantic-ai-agent-creation skill guides PydanticAI agent setup with typed dependencies, validated outputs, and model configuration. Use it when building agents or chat systems. CX Codex +1 219installs ai-elements A skill for Claude Code, Codex, Cursor, Copilot, Gemini CLI and OpenCode: helps build chat interfaces, job queues, tool execution displays and approval workflows. Triggers on ai-elements, Queue, Tool, Confirmation, Message, PromptInput. CX Codex +1 211installs shadcn-code-review shadcn-code-review audits React components built with shadcn/ui, Radix primitives, and Tailwind CSS. Catches CVA mistakes, broken asChild slots, and missing accessibility states. CX Codex +1 206installs react-router-code-review react-router-code-review is a Claude Code skill that checks React Router v6.4+ code for loaders, actions, error boundaries, and navigation. It reviews routing changes. CX Codex +1 202installs swift-testing-code-review swift-testing-code-review reviews Swift Testing code for macro usage, parameterized and async tests, and suite structure. Use it when checking .swift files. CX Codex +1 196installs docs-style docs-style enforces technical documentation style rules, Diataxis framework alignment, active voice, and clear structures for both readers and LLMs. CX Codex +1 180installs

Project sponsors

Companies that keep this analytics open