gophers
26 production-grade Go programming skills for Gemini CLI — fundamentals, concurrency, web, data, observability, testing, code review.
Open source Open in the app JSON README (API)
About
26 production-grade Go programming skills for Gemini CLI — fundamentals, concurrency, web, data, observability, testing, code review.
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- muratmirgun
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.0
- Stars
- 8
- Forks
- 1
- Last push
- 2026-08-11T13:07:29Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
muratmirgun/gophers
README
<div align="center">
# 🐹 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)
</div>
---
## 🎯 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-<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
<details>
<summary><strong>Do I need to install all 26 skills?</strong></summary>
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.
</details>
<details>
<summary><strong>Can I use these without Claude Code?</strong></summary>
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.
</details>
<details>
<summary><strong>Why "26 skills" and not "1 big style guide"?</strong></summary>
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.
</details>
<details>
<summary><strong>Are these compatible with `golangci-lint`?</strong></summary>
Yes — `go-linting` ships an opinionated `.golangci.yml` and the other skills cite the same checks. No conflicts.
</details>
<details>
<summary><strong>What Go version do these target?</strong></summary>
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.
</details>
<details>
<summary><strong>How do I propose a new skill?</strong></summary>
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.
</details>
---
## 🤝 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
---
<div align="center">
**[⬆ back to top](#-gophers)**
*Built with Claude Code. Reviewed by Claude Code. Used by Claude Code.*
</div>