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

imageLicense: MIT imageGo Version imageSkills imageClaude Code imageGemini CLI imageopencode imagePRs Welcome

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.

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

⚙️ Concurrency — goroutines without surprises

🌐 Web & APIs — framework-agnostic delivery layers

🗄️ Data & Observability — production signal

🧪 Quality & Process — ship safely

🔬 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

🛠️ 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

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 for the full authoring checklist.

📜 License

MIT © muratmirgun

Influenced by:

• Effective Go — the original style scripture
• Google Go Style Guide — readability rules
• Uber Go Style Guide — production patterns
• samber/cc-skills-golang — library-specific skills
• cxuu/golang-skills — language fundamentals

⬆ back to top

Built with Claude Code. Reviewed by Claude Code. Used by Claude Code.