{
  "markdown": "<div align=\"center\">\n\n# 🐹 gophers\n\n**26 production-grade Go skills for Claude Code, Gemini CLI, and opencode.**\nBattle-tested patterns from the Go community — codified as triggerable AI skills.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Go Version](https://img.shields.io/badge/Go-1.21%2B-00ADD8?logo=go)](https://golang.org)\n[![Skills](https://img.shields.io/badge/skills-26-blueviolet)](skills/)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-compatible-d97757)](https://docs.claude.com/en/docs/claude-code)\n[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-compatible-4285F4?logo=google)](https://github.com/google-gemini/gemini-cli)\n[![opencode](https://img.shields.io/badge/opencode-compatible-black)](https://opencode.ai)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#-contributing)\n\n[**Quick Start**](#-quick-start) • [**Agent Plugins**](#-portable-agent-plugins) • [**Skills Catalog**](#-skills-catalog) • [**How It Works**](#-how-it-works) • [**Examples**](#-examples) • [**FAQ**](#-faq)\n\n</div>\n\n---\n\n## 🎯 Why gophers?\n\nMost 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*.\n\n> \"The bigger the interface, the weaker the abstraction.\" — Rob Pike\n> Now your AI knows that, before it writes a 12-method `UserManagerService`.\n\n**What you get:**\n\n- 🧠 **Discoverable** — Each skill has an explicit trigger description; Claude knows *when* to use it.\n- 📚 **Progressive disclosure** — `SKILL.md` is ≤ 200 lines; deep dives live in `references/`.\n- 🪞 **Opinionated** — Every rule cites a community source (Effective Go, Google Style Guide, Uber, Rob Pike talks).\n- 🔌 **Multi-platform** — Same skill files run in Claude Code, Gemini CLI, and opencode.\n- ✅ **Verifiable** — Every skill ends with a checklist your AI can self-grade against.\n\n---\n\n## 🚀 Quick Start\n\n### Claude Code (via marketplace)\n\n```bash\n# Add the marketplace\n/plugin marketplace add muratmirgun/gophers\n\n# Install the plugin\n/plugin install gophers@gophers\n```\n\n### Claude Code (manual)\n\n```bash\ncd ~/.claude/plugins\ngit clone https://github.com/muratmirgun/gophers\n```\n\nThen restart Claude Code. Skills auto-load from `skills/`.\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/muratmirgun/gophers\n```\n\n### opencode\n\n```bash\nopencode plugin add github.com/muratmirgun/gophers\n```\n\n### Manual / any other agent\n\n```bash\ngit clone https://github.com/muratmirgun/gophers ~/.config/ai/gophers\n# Point your agent's CLAUDE.md / AGENTS.md / GEMINI.md at the skills/ directory.\n```\n\n---\n\n## 🔌 Portable Agent Plugins\n\n**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.\n\nAgent 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.\n\n| Package part | Portability |\n|---|---|\n| `plugin.json` | Portable Agent Plugins manifest |\n| `skills/` | Portable Agent Skills and canonical content |\n| `.claude-plugin/` | Claude Code manifest and generated invocation compatibility |\n| `gemini-extension.json` | Gemini CLI integration |\n| `opencode.json` | OpenCode integration |\n| `agents/` | Client-specific prompts; Agent Plugins 1.0.0 has no portable mapping |\n\nThe 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.\n\nMaintainers can validate the complete package with one command:\n\n```bash\nscripts/validate.sh\n```\n\nThis 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.\n\n---\n\n## 📦 Skills Catalog\n\n26 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.\n\n### 🧱 Fundamentals — *language mechanics, taught well*\n\n| Skill | Emoji | Triggers when… |\n|---|:---:|---|\n| [go-naming](skills/go-naming) | 🏷️ | naming any identifier — packages, types, methods, errors |\n| [go-declarations](skills/go-declarations) | 📝 | declaring vars, consts, structs, maps, iota enums |\n| [go-control-flow](skills/go-control-flow) | 🔀 | writing conditionals, loops, switches, type switches |\n| [go-functions](skills/go-functions) | ƒ | organising functions in a file, designing signatures |\n| [go-data-structures](skills/go-data-structures) | 📊 | choosing/operating on slices, maps, arrays, strings |\n| [go-packages](skills/go-packages) | 📦 | creating packages, organising imports, structuring projects |\n| [go-error-handling](skills/go-error-handling) | ⚠️ | writing, wrapping, inspecting, or logging errors |\n| [go-interfaces](skills/go-interfaces) | 🔌 | defining/implementing interfaces, embedding, receivers |\n| [go-generics](skills/go-generics) | 🧬 | deciding whether to introduce generics, writing constraints |\n| [go-functional-options](skills/go-functional-options) | ⚙️ | designing constructors with 3+ optional parameters |\n| [go-defensive](skills/go-defensive) | 🛡️ | hardening API boundaries — copy, defer, time, panic discipline |\n| [go-code-style](skills/go-code-style) | ✨ | writing/reviewing for clarity, formatting, design priority |\n\n### ⚙️ Concurrency — *goroutines without surprises*\n\n| Skill | Emoji | Triggers when… |\n|---|:---:|---|\n| [go-context](skills/go-context) | 📦 | designing context.Context flow, deadlines, request values |\n| [go-concurrency](skills/go-concurrency) | 🚦 | writing goroutines, channels, select, mutexes, errgroup |\n\n### 🌐 Web & APIs — *framework-agnostic delivery layers*\n\n| Skill | Emoji | Triggers when… |\n|---|:---:|---|\n| [go-clean-architecture](skills/go-clean-architecture) | 🏛️ | scaffolding a service into Domain/Usecase/Repository/Delivery |\n| [go-grpc](skills/go-grpc) | 📡 | implementing or reviewing gRPC servers/clients |\n| [go-graphql](skills/go-graphql) | 🌐 | building a GraphQL API (gqlgen or graph-gophers) |\n| [go-swagger](skills/go-swagger) | 📋 | adding OpenAPI/Swagger annotations with swaggo/swag |\n\n### 🗄️ Data & Observability — *production signal*\n\n| Skill | Emoji | Triggers when… |\n|---|:---:|---|\n| [go-database](skills/go-database) | 🗄️ | writing SQL access code — sqlx/sqlc/pgx/GORM trade-offs |\n| [go-logging](skills/go-logging) | 📝 | choosing a logger, configuring slog, request-scoped fields |\n| [go-observability](skills/go-observability) | 📈 | instrumenting metrics, traces, exemplars, correlation |\n| [go-performance](skills/go-performance) | ⚡ | profiling, benchmarking, optimising — pprof decision tree |\n\n### 🧪 Quality & Process — *ship safely*\n\n| Skill | Emoji | Triggers when… |\n|---|:---:|---|\n| [go-testing](skills/go-testing) | 🧪 | writing tests — table-driven, subtests, fuzz, synctest, goleak |\n| [go-linting](skills/go-linting) | 🧹 | setting up golangci-lint, suppressing findings, CI gates |\n| [go-documentation](skills/go-documentation) | 📚 | writing godoc comments, Example tests, README/CHANGELOG |\n| [go-code-review](skills/go-code-review) | 👀 | **user-invokable** — `/go-code-review` walks a diff topic by topic |\n\n---\n\n## 🔬 How It Works\n\nEach skill is a **single markdown file** (`SKILL.md`) with structured frontmatter and a strict body shape:\n\n```yaml\n---\nname: go-interfaces\ndescription: Use when defining or implementing Go interfaces...   # ← trigger\nlicense: MIT\nmetadata:\n  author: muratmirgun\n  version: \"0.1.0\"\nallowed-tools: Read Edit Write Glob Grep Bash(go:*)\n---\n\n# Title\n1-2 sentence philosophy.\n\n## Core Rules            ← 5-7 numbered, non-negotiable invariants\n## Decision Table        ← when to apply / when not to\n## Body sections         ← code examples, contrasts (Good / Bad)\n## Anti-Patterns         ← table of common mistakes + fixes\n## Verification Checklist← AI self-grades before claiming done\n## References            ← links to deeper references/*.md\n```\n\nWhen 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\".\n\n---\n\n## 💡 Examples\n\n### Before gophers\n\n```go\ntype UserManagerInterface interface {\n    GetUser(id string) (*User, error)\n    SetUser(u *User) error\n    DeleteUser(id string) error\n    ListUsers() ([]*User, error)\n    CountUsers() (int, error)\n}\n\nfunc GetUser(id string) (*User, error) {\n    user, err := db.QueryUser(id)\n    if err != nil {\n        return nil, fmt.Errorf(\"db error: \" + err.Error())\n    }\n    return user, nil\n}\n```\n\n### After gophers (`go-interfaces` + `go-error-handling` + `go-naming` fire)\n\n```go\n// Reader fetches a User by ID. Returns ErrNotFound when absent.\ntype Reader interface {\n    User(ctx context.Context, id string) (*User, error)\n}\n\nfunc (s *Store) User(ctx context.Context, id string) (*User, error) {\n    u, err := s.db.User(ctx, id)\n    if err != nil {\n        return nil, fmt.Errorf(\"store: user %s: %w\", id, err)\n    }\n    return u, nil\n}\n```\n\nWhat changed:\n\n- **5-method `UserManagerInterface` → 1-method `Reader`** (small interfaces compose)\n- **`GetUser` → `User`** (Go style: no `Get` prefix)\n- **`\"db error: \" + err.Error()` → `%w`** (preserves `errors.Is` / `errors.As`)\n- **`context.Context` first param** (cancellation propagates)\n\n---\n\n## 🎨 The gophers Philosophy\n\n| Tenet | What it means in practice |\n|---|---|\n| **Errors are values** | No `panic`-as-exception, no swallowed errors, wrap with `%w` |\n| **Accept interfaces, return concrete types** | Consumers state needs; producers expose what they have |\n| **The framework is a detail** | Gin/Echo/Fiber lives in `internal/delivery/`, nothing else |\n| **The database is a detail** | SQL lives in `internal/repository/`, nothing else |\n| **Tests fail usefully** | `Function(input) = got, want want` — always |\n| **Documentation is part of the API** | godoc renders in IDE tooltips; signature noise is wasted ink |\n| **Measure before optimising** | pprof first, intuition last |\n| **Don't design with interfaces — discover them** | Wait for the second implementation |\n\n---\n\n## 🛠️ Project Structure\n\n```\ngophers/\n├── plugin.json                  # Portable Agent Plugins 1.0.0 manifest\n├── .claude-plugin/\n│   ├── plugin.json           # Claude Code plugin manifest\n│   ├── marketplace.json      # Claude Code marketplace listing\n│   ├── skill-overrides.json  # Client-only invocation and OpenClaw values\n│   └── skills/               # Generated Claude/OpenClaw compatibility files\n├── .github/workflows/\n│   └── validate.yml          # Complete package validation\n├── gemini-extension.json     # Gemini CLI extension manifest\n├── opencode.json             # opencode plugin manifest\n├── skills/                   # 26 canonical portable skills\n│   └── go-<name>/\n│       ├── SKILL.md          # ≤ 200 lines, opinionated rules\n│       └── references/       # Deep dives, examples, cheat-sheets\n├── agents/                   # Subagent prompts (extensible)\n├── scripts/                  # Generation, tests, and validation\n├── CLAUDE.md                 # Project context for AI assistants\n└── README.md                 # You are here\n```\n\n---\n\n## ❓ FAQ\n\n<details>\n<summary><strong>Do I need to install all 26 skills?</strong></summary>\n\nNo. 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.\n</details>\n\n<details>\n<summary><strong>Can I use these without Claude Code?</strong></summary>\n\nYes. 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.\n</details>\n\n<details>\n<summary><strong>Why \"26 skills\" and not \"1 big style guide\"?</strong></summary>\n\nToken budget. A 5,000-line style guide poisons context. 26 focused skills with explicit triggers load only what's relevant to the current diff.\n</details>\n\n<details>\n<summary><strong>Are these compatible with `golangci-lint`?</strong></summary>\n\nYes — `go-linting` ships an opinionated `.golangci.yml` and the other skills cite the same checks. No conflicts.\n</details>\n\n<details>\n<summary><strong>What Go version do these target?</strong></summary>\n\nGo 1.21+ baseline. A few skills reference Go 1.24+ (`b.Loop`) and Go 1.25+ (`testing/synctest`) — they call out the version explicitly.\n</details>\n\n<details>\n<summary><strong>How do I propose a new skill?</strong></summary>\n\nOpen 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.\n</details>\n\n---\n\n## 🤝 Contributing\n\nPRs welcome — but the **skill bar is high**:\n\n1. **Trigger must be unambiguous.** \"Use when X\" — not \"Use when working on Go\".\n2. **Every rule cites a source.** Effective Go, Google Style Guide, Uber, a standard-library API, or a Rob Pike talk. No bare opinions.\n3. **`SKILL.md` ≤ 200 lines.** Deep content goes in `references/`.\n4. **Every skill ends with a verification checklist.** Items must be observable (a `go vet` flag, an `errors.Is` call, a grep pattern).\n5. **No emoji in body text** unless the user requested them. Frontmatter `emoji:` field is the only exception.\n\nSee [CLAUDE.md](CLAUDE.md) for the full authoring checklist.\n\n---\n\n## 📜 License\n\nMIT © [muratmirgun](https://github.com/muratmirgun)\n\nInfluenced by:\n\n- [Effective Go](https://go.dev/doc/effective_go) — the original style scripture\n- [Google Go Style Guide](https://google.github.io/styleguide/go/) — readability rules\n- [Uber Go Style Guide](https://github.com/uber-go/guide) — production patterns\n- [samber/cc-skills-golang](https://github.com/samber/cc-skills-golang) — library-specific skills\n- [cxuu/golang-skills](https://github.com/cxuu/golang-skills) — language fundamentals\n\n---\n\n<div align=\"center\">\n\n**[⬆ back to top](#-gophers)**\n\n*Built with Claude Code. Reviewed by Claude Code. Used by Claude Code.*\n\n</div>\n",
  "bytes": 14811,
  "sha": "53882a315fdc984bc7a4b2e49d7f46dcf7a550d948c363015d11bcae18e82447",
  "repo_slug": "muratmirgun/gophers",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_muratmirgun_gophers_e220a87a/readme"
}