KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

gophers

★ 8 Open GitHub ↗

26 production-grade Go skills for Claude Code, Gemini CLI, and opencode.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🐹 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: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/muratmirgun/gophers/main/LICENSE)
[![Go Version](https://img.shields.io/badge/Go-1.21%2B-00ADD8?logo=go)](https://golang.org)
[![Skills](https://img.shields.io/badge/skills-26-blueviolet)](https://raw.githubusercontent.com/muratmirgun/gophers/main/skills/)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-compatible-d97757)](https://docs.claude.com/en/docs/claude-code)
[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-compatible-4285F4?logo=google)](https://github.com/google-gemini/gemini-cli)
[![opencode](https://img.shields.io/badge/opencode-compatible-black)](https://opencode.ai)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://raw.githubusercontent.com/muratmirgun/gophers/main/)

[**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

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.*

</div>

gophers

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README