🐹 gophers

26 production-grade Go skills for Claude Code, Gemini CLI, and opencode. Battle-tested patterns from the Go community — codified as triggerable AI skills.

Quick Start • Skills Catalog • How It Works • Examples • FAQ

---

🎯 Why gophers?

Most AI assistants write Go like a senior JavaScript engineer pretending to like semicolons. gophers plugs in 26 opinionated skills that teach Claude (and friends) to write Go the way the standard library does — small interfaces, errors as values, no magic.

"The bigger the interface, the weaker the abstraction." — Rob Pike Now your AI knows that, before it writes a 12-method UserManagerService.

What you get:

• 🧠 Discoverable — Each skill has an explicit trigger description; Claude knows when to use it.
• 📚 Progressive disclosure — SKILL.md is ≤ 200 lines; deep dives live in references/.
• 🪞 Opinionated — Every rule cites a community source (Effective Go, Google Style Guide, Uber, Rob Pike talks).
• 🔌 Multi-platform — Same skill files run in Claude Code, Gemini CLI, and opencode.
• ✅ Verifiable — Every skill ends with a checklist your AI can self-grade against.

---

🚀 Quick Start

Claude Code (via marketplace)

# Add the marketplace
/plugin marketplace add muratmirgun/gophers

# Install the plugin
/plugin install gophers@gophers

Claude Code (manual)

cd ~/.claude/plugins
git clone https://github.com/muratmirgun/gophers

Then restart Claude Code. Skills auto-load from skills/.

Gemini CLI

gemini extensions install https://github.com/muratmirgun/gophers

opencode

opencode plugin add github.com/muratmirgun/gophers

Manual / any other agent

git clone https://github.com/muratmirgun/gophers ~/.config/ai/gophers
# Point your agent's CLAUDE.md / AGENTS.md / GEMINI.md at the skills/ directory.

---

📦 Skills Catalog

26 skills, grouped by intent. One is user-invokable (/go-code-review); the rest activate automatically when their trigger conditions match.

🧱 Fundamentals — language mechanics, taught well

Skill	Emoji	Triggers when…
go-naming	🏷️	naming any identifier — packages, types, methods, errors
go-declarations	📝	declaring vars, consts, structs, maps, iota enums
go-control-flow	🔀	writing conditionals, loops, switches, type switches
go-functions	ƒ	organising functions in a file, designing signatures
go-data-structures	📊	choosing/operating on slices, maps, arrays, strings
go-packages	📦	creating packages, organising imports, structuring projects
go-error-handling	⚠️	writing, wrapping, inspecting, or logging errors
go-interfaces	🔌	defining/implementing interfaces, embedding, receivers
go-generics	🧬	deciding whether to introduce generics, writing constraints
go-functional-options	⚙️	designing constructors with 3+ optional parameters
go-defensive

⚙️ Concurrency — goroutines without surprises

Skill	Emoji	Triggers when…
go-context	📦	designing context.Context flow, deadlines, request values
go-concurrency	🚦	writing goroutines, channels, select, mutexes, errgroup

🌐 Web & APIs — framework-agnostic delivery layers

Skill	Emoji	Triggers when…
go-clean-architecture	🏛️	scaffolding a service into Domain/Usecase/Repository/Delivery
go-grpc	📡	implementing or reviewing gRPC servers/clients
go-graphql	🌐	building a GraphQL API (gqlgen or graph-gophers)
go-swagger	📋	adding OpenAPI/Swagger annotations with swaggo/swag

🗄️ Data & Observability — production signal

Skill	Emoji	Triggers when…
go-database	🗄️	writing SQL access code — sqlx/sqlc/pgx/GORM trade-offs
go-logging	📝	choosing a logger, configuring slog, request-scoped fields
go-observability	📈	instrumenting metrics, traces, exemplars, correlation
go-performance	⚡	profiling, benchmarking, optimising — pprof decision tree

🧪 Quality & Process — ship safely

Skill	Emoji	Triggers when…
go-testing	🧪	writing tests — table-driven, subtests, fuzz, synctest, goleak
go-linting	🧹	setting up golangci-lint, suppressing findings, CI gates
go-documentation	📚	writing godoc comments, Example tests, README/CHANGELOG
go-code-review	👀	user-invokable — /go-code-review walks a diff topic by topic

---

🔬 How It Works

Each skill is a single markdown file (SKILL.md) with structured frontmatter and a strict body shape:

---
name: go-interfaces
description: Use when defining or implementing Go interfaces...   # ← trigger
user-invocable: false                                              # auto-fires
license: MIT
metadata:
  openclaw:
    emoji: "🔌"
    requires: { bins: [go] }
allowed-tools: Read Edit Write Glob Grep Bash(go:*)
---

# Title
1-2 sentence philosophy.

## Core Rules            ← 5-7 numbered, non-negotiable invariants
## Decision Table        ← when to apply / when not to
## Body sections         ← code examples, contrasts (Good / Bad)
## Anti-Patterns         ← table of common mistakes + fixes
## Verification Checklist← AI self-grades before claiming done
## References            ← links to deeper references/*.md

When Claude (or Gemini / opencode) reads code that matches the trigger, the skill is injected into context — opinionated rules + code examples + a verification checklist. Your AI assistant goes from "knows Go" to "writes Go like a stdlib author".

---

💡 Examples

Before gophers

type UserManagerInterface interface {
    GetUser(id string) (*User, error)
    SetUser(u *User) error
    DeleteUser(id string) error
    ListUsers() ([]*User, error)
    CountUsers() (int, error)
}

func GetUser(id string) (*User, error) {
    user, err := db.QueryUser(id)
    if err != nil {
        return nil, fmt.Errorf("db error: " + err.Error())
    }
    return user, nil
}

After gophers (go-interfaces + go-error-handling + go-naming fire)

// Reader fetches a User by ID. Returns ErrNotFound when absent.
type Reader interface {
    User(ctx context.Context, id string) (*User, error)
}

func (s *Store) User(ctx context.Context, id string) (*User, error) {
    u, err := s.db.User(ctx, id)
    if err != nil {
        return nil, fmt.Errorf("store: user %s: %w", id, err)
    }
    return u, nil
}

What changed:

• 5-method UserManagerInterface → 1-method Reader (small interfaces compose)
• GetUser → User (Go style: no Get prefix)
• "db error: " + err.Error() → %w (preserves errors.Is / errors.As)
• context.Context first param (cancellation propagates)

---

🎨 The gophers Philosophy

Tenet	What it means in practice
Errors are values	No panic-as-exception, no swallowed errors, wrap with %w
Accept interfaces, return concrete types	Consumers state needs; producers expose what they have
The framework is a detail	Gin/Echo/Fiber lives in internal/delivery/, nothing else
The database is a detail	SQL lives in internal/repository/, nothing else
Tests fail usefully	Function(input) = got, want want — always
Documentation is part of the API	godoc renders in IDE tooltips; signature noise is wasted ink
Measure before optimising	pprof first, intuition last
Don't design with interfaces — discover them	Wait for the second implementation

---

🛠️ Project Structure

gophers/
├── .claude-plugin/
│   ├── plugin.json           # Claude Code plugin manifest
│   └── marketplace.json      # Claude Code marketplace listing
├── gemini-extension.json     # Gemini CLI extension manifest
├── opencode.json             # opencode plugin manifest
├── skills/                   # 26 skills, each a folder
│   └── go-<name>/
│       ├── SKILL.md          # ≤ 200 lines, opinionated rules
│       └── references/       # Deep dives, examples, cheat-sheets
├── agents/                   # Subagent prompts (extensible)
├── scripts/                  # Validation & packaging
├── CLAUDE.md                 # Project context for AI assistants
└── README.md                 # You are here

---

❓ FAQ

No. Each skill activates independently based on its trigger description. If you never write GraphQL, go-graphql never fires. The cost of an unused skill is zero tokens.

Yes. The skills are plain markdown — usable as system prompts for any LLM. The plugin manifests just automate discovery for Claude Code, Gemini CLI, and opencode.

Token budget. A 5,000-line style guide poisons context. 26 focused skills with explicit triggers load only what's relevant to the current diff.

Yes — go-linting ships an opinionated .golangci.yml and the other skills cite the same checks. No conflicts.

Go 1.21+ baseline. A few skills reference Go 1.24+ (b.Loop) and Go 1.25+ (testing/synctest) — they call out the version explicitly.

Open an issue with the skill name, the trigger conditions, and 2-3 concrete rules it would enforce. We reject vague "best practices" skills — every skill must have a verifiable checklist.

---

🤝 Contributing

PRs welcome — but the skill bar is high:

1. Trigger must be unambiguous. "Use when X" — not "Use when working on Go".
2. Every rule cites a source. Effective Go, Google Style Guide, Uber, a standard-library API, or a Rob Pike talk. No bare opinions.
3. SKILL.md ≤ 200 lines. Deep content goes in references/.
4. Every skill ends with a verification checklist. Items must be observable (a go vet flag, an errors.Is call, a grep pattern).
5. No emoji in body text unless the user requested them. Frontmatter emoji: field is the only exception.

See CLAUDE.md for the full authoring checklist.

---

📜 License

MIT © muratmirgun

Influenced by:

• Effective Go — the original style scripture
• Google Go Style Guide — readability rules
• Uber Go Style Guide — production patterns
• samber/cc-skills-golang — library-specific skills
• cxuu/golang-skills — language fundamentals

---

⬆ back to top

Built with Claude Code. Reviewed by Claude Code. Used by Claude Code.