# πΉ 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.
[](LICENSE)
[](https://golang.org)
[](skills/)
[](https://docs.claude.com/en/docs/claude-code)
[](https://github.com/google-gemini/gemini-cli)
[](https://opencode.ai)
[](#-contributing)
[**Quick Start**](#-quick-start) β’ [**Agent Plugins**](#-portable-agent-plugins) β’ [**Skills Catalog**](#-skills-catalog) β’ [**How It Works**](#-how-it-works) β’ [**Examples**](#-examples) β’ [**FAQ**](#-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)
```bash
# Add the marketplace
/plugin marketplace add muratmirgun/gophers
# Install the plugin
/plugin install gophers@gophers
```
### Claude Code (manual)
```bash
cd ~/.claude/plugins
git clone https://github.com/muratmirgun/gophers
```
Then restart Claude Code. Skills auto-load from `skills/`.
### Gemini CLI
```bash
gemini extensions install https://github.com/muratmirgun/gophers
```
### opencode
```bash
opencode plugin add github.com/muratmirgun/gophers
```
### Manual / any other agent
```bash
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](https://agent-plugins.org/) plugin. The root [`plugin.json`](plugin.json) is the portable manifest. Compatible clients discover each immediate skill directory under root [`skills/`](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](https://agent-plugins.org/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:
```bash
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](skills/go-naming) | π·οΈ | naming any identifier β packages, types, methods, errors |
| [go-declarations](skills/go-declarations) | π | declaring vars, consts, structs, maps, iota enums |
| [go-control-flow](skills/go-control-flow) | π | writing conditionals, loops, switches, type switches |
| [go-functions](skills/go-functions) | Ζ | organising functions in a file, designing signatures |
| [go-data-structures](skills/go-data-structures) | π | choosing/operating on slices, maps, arrays, strings |
| [go-packages](skills/go-packages) | π¦ | creating packages, organising imports, structuring projects |
| [go-error-handling](skills/go-error-handling) | β οΈ | writing, wrapping, inspecting, or logging errors |
| [go-interfaces](skills/go-interfaces) | π | defining/implementing interfaces, embedding, receivers |
| [go-generics](skills/go-generics) | 𧬠| deciding whether to introduce generics, writing constraints |
| [go-functional-options](skills/go-functional-options) | βοΈ | designing constructors with 3+ optional parameters |
| [go-defensive](skills/go-defensive) | π‘οΈ | hardening API boundaries β copy, defer, time, panic discipline |
| [go-code-style](skills/go-code-style) | β¨ | writing/reviewing for clarity, formatting, design priority |
### βοΈ Concurrency β *goroutines without surprises*
| Skill | Emoji | Triggers when⦠|
|---|:---:|---|
| [go-context](skills/go-context) | π¦ | designing context.Context flow, deadlines, request values |
| [go-concurrency](skills/go-concurrency) | π¦ | writing goroutines, channels, select, mutexes, errgroup |
### π Web & APIs β *framework-agnostic delivery layers*
| Skill | Emoji | Triggers when⦠|
|---|:---:|---|
| [go-clean-architecture](skills/go-clean-architecture) | ποΈ | scaffolding a service into Domain/Usecase/Repository/Delivery |
| [go-grpc](skills/go-grpc) | π‘ | implementing or reviewing gRPC servers/clients |
| [go-graphql](skills/go-graphql) | π | building a GraphQL API (gqlgen or graph-gophers) |
| [go-swagger](skills/go-swagger) | π | adding OpenAPI/Swagger annotations with swaggo/swag |
### ποΈ Data & Observability β *production signal*
| Skill | Emoji | Triggers when⦠|
|---|:---:|---|
| [go-database](skills/go-database) | ποΈ | writing SQL access code β sqlx/sqlc/pgx/GORM trade-offs |
| [go-logging](skills/go-logging) | π | choosing a logger, configuring slog, request-scoped fields |
| [go-observability](skills/go-observability) | π | instrumenting metrics, traces, exemplars, correlation |
| [go-performance](skills/go-performance) | β‘ | profiling, benchmarking, optimising β pprof decision tree |
### π§ͺ Quality & Process β *ship safely*
| Skill | Emoji | Triggers when⦠|
|---|:---:|---|
| [go-testing](skills/go-testing) | π§ͺ | writing tests β table-driven, subtests, fuzz, synctest, goleak |
| [go-linting](skills/go-linting) | π§Ή | setting up golangci-lint, suppressing findings, CI gates |
| [go-documentation](skills/go-documentation) | π | writing godoc comments, Example tests, README/CHANGELOG |
| [go-code-review](skills/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:
```yaml
---
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
```go
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)
```go
// 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-/
β βββ 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
Do I need to install all 26 skills?
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.
Can I use these without Claude Code?
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.
Why "26 skills" and not "1 big style guide"?
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.
Are these compatible with `golangci-lint`?
Yes β `go-linting` ships an opinionated `.golangci.yml` and the other skills cite the same checks. No conflicts.
What Go version do these target?
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.
How do I propose a new skill?
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](CLAUDE.md) for the full authoring checklist.
---
## π License
MIT Β© [muratmirgun](https://github.com/muratmirgun)
Influenced by:
- [Effective Go](https://go.dev/doc/effective_go) β the original style scripture
- [Google Go Style Guide](https://google.github.io/styleguide/go/) β readability rules
- [Uber Go Style Guide](https://github.com/uber-go/guide) β production patterns
- [samber/cc-skills-golang](https://github.com/samber/cc-skills-golang) β library-specific skills
- [cxuu/golang-skills](https://github.com/cxuu/golang-skills) β language fundamentals
---
**[β¬ back to top](#-gophers)**
*Built with Claude Code. Reviewed by Claude Code. Used by Claude Code.*