gophers

🐹 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 • Agent Plugins • 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.

---

🔌 Portable Agent Plugins

gophers is also packaged as an Agent Plugins 1.0.0 plugin. The root plugin.json is the portable manifest. Compatible clients discover each immediate skill directory under root skills/ automatically.

Agent Plugins defines package contents and discovery. Each client controls installation, distribution, enablement, updates, marketplace publication, and user interface. The standard does not define a universal installation command. See the current compatible clients for client support.

Package part	Portability
plugin.json	Portable Agent Plugins manifest
skills/	Portable Agent Skills and canonical content
.claude-plugin/	Claude Code manifest and generated invocation compatibility
gemini-extension.json	Gemini CLI integration
opencode.json	OpenCode integration
agents/	Client-specific prompts; Agent Plugins 1.0.0 has no portable mapping

The Claude Code compatibility tree is generated from root skills. It retains user-invocable controls and existing OpenClaw metadata without adding non-portable fields to canonical skills. The package needs no mcp.json because its capabilities are instructions and reference files, not runtime MCP tools.

Maintainers can validate the complete package with one command:

scripts/validate.sh

This command validates the live Agent Plugins schema, all 26 skills through the pinned official skills-ref library, local links, client JSON files, generated files, and existing repository rules.

---

📦 Skills Catalog

26 skills, grouped by intent. In Claude Code, one is user-invokable (/go-code-review); the generated client layer hides the rest from the slash menu while keeping automatic activation.

🧱 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	🛡️	hardening API boundaries — copy, defer, time, panic discipline
go-code-style	✨	writing/reviewing for clarity, formatting, design priority

⚙️ 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
license: MIT
metadata:
  author: muratmirgun
  version: "0.1.0"
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/
├── plugin.json                  # Portable Agent Plugins 1.0.0 manifest
├── .claude-plugin/
│   ├── plugin.json           # Claude Code plugin manifest
│   ├── marketplace.json      # Claude Code marketplace listing
│   ├── skill-overrides.json  # Client-only invocation and OpenClaw values
│   └── skills/               # Generated Claude/OpenClaw compatibility files
├── .github/workflows/
│   └── validate.yml          # Complete package validation
├── gemini-extension.json     # Gemini CLI extension manifest
├── opencode.json             # opencode plugin manifest
├── skills/                   # 26 canonical portable skills
│   └── go-<name>/
│       ├── SKILL.md          # ≤ 200 lines, opinionated rules
│       └── references/       # Deep dives, examples, cheat-sheets
├── agents/                   # Subagent prompts (extensible)
├── scripts/                  # Generation, tests, and validation
├── CLAUDE.md                 # Project context for AI assistants
└── README.md                 # You are here

---

❓ FAQ