Skip to main content
skill CX Codex

writing-go — Claude Code skill: idiomatic Go 1.25+

writing-go pins your coding agent to a fixed set of Go conventions: start from the standard library, prefer concrete types, wrap errors with context, test in tables.

MIT 110 installs ★ 17 updated 2026-10-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add julianobarbosa/claude-code-skills --skill writing-go -a claude-code
Open on GitHub

What writing-go does

The skill sets the house style your agent follows in Go: start from the standard library and justify any dependency you add, declare interfaces where they are consumed, hand back structs instead of abstractions. It carries short snippets for wrapping errors with %w, for a constructor that takes functional options, and for table-driven tests. Three companion files go deeper: PATTERNS.md, TESTING.md and CLI.md.

Go 1.25 material gets its own section — testing/synctest with a simulated clock, the experimental encoding/json/v2 behind GOEXPERIMENT=jsonv2, runtime/trace.FlightRecorder, cgroup-aware GOMAXPROCS, and the GreenTea GC experiment. A gotcha list follows: defer freezes its arguments when the line runs, a send to a nil channel blocks for good, and a sync.Pool entry can be collected before you read it back.

The test snippets call require and assert, so testify has to be in the module or those examples won't compile. Tool access stops at Read, Bash, Grep and Glob.

What it helps with

  • settle where interfaces live in a new Go package
  • wrap an error with context instead of returning it bare
  • build a constructor that takes functional options
  • convert ad-hoc checks into table-driven tests
  • find out which Go 1.25 features sit behind GOEXPERIMENT

Example prompts for the agent

  • Write the HTTP client in Go 1.25 following the skill: standard library only, and wrap errors with %w.
  • Refactor this package so interfaces sit with the consumer and functions return concrete structs.
  • Run my code against the gotcha list and sketch table-driven tests for Process.

How to install writing-go

1Skills CLI (Vercel)

npx skills add julianobarbosa/claude-code-skills --skill writing-go -a claude-code

2Manually: put the files in place

~/.claude/skills/writing-go/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/writing-go/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about writing-go

How do I install writing-go in Claude Code?

Run npx skills add julianobarbosa/claude-code-skills --skill writing-go -a claude-code. The skill lands at ~/.claude/skills/writing-go/SKILL.md.

What does writing-go do?

It gives the agent Go 1.25+ conventions to follow while writing or reviewing code: fewer dependencies, concrete return types, errors carrying context, table-driven tests. Companion files cover patterns, testing and CLI layout.

What do the testing examples depend on?

They call require and assert, which come from testify, so the module needs it. TESTING.md also covers generating mocks with mockery.

Source text

SKILL.md · MIT
---
name: writing-go
description: Idiomatic Go 1.25+ development. Use when writing Go code, designing APIs, discussing Go patterns, or reviewing Go implementations. Emphasizes stdlib, concrete types, simple error handling, and minimal dependencies.
allowed-tools: Read, Bash, Grep, Glob
---

# Go Development (1.25+)

## Core Principles

- **Stdlib first**: External deps only when justified
- **Concrete types**: Define interfaces at consumer, return structs
- **Composition**: Over inheritance, always
- **Fail fast**: Clear errors with context
- **Simple**: The obvious solution is usually correct

## Quick Patterns

### Error Handling

```go
if err := doThing(); err != nil {
    return fmt.Errorf("do thing: %w", err)
}
```

### Struct with Options

```go
type Server struct {
    addr    string
    timeout time.Duration
}

func NewServer(addr string, opts ...Option) *Server {
    s := &Server{addr: addr, timeout: 30 * time.Second}
    for _, opt := range opts {
        opt(s)
    }
    return s
}
```

### Table-Driven Tests

```go
tests := []struct {
    name    string
    input   string
    want    string
    wantErr bool
}{
    {"valid", "hello", "HELLO", false},
    {"empty", "", "", true},
}
for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {
        got, err := Process(tt.input)
        if tt.wantErr {
            require.Error(t, err)
            return
        }
        require.NoError(t, err)
        assert.Equal(t, tt.want, got)
    })
}
```

## Go 1.25 Features

- **testing/synctest**: Deterministic concurrent testing with simulated clock
- **encoding/json/v2**: Experimental, 3-10x faster (GOEXPERIMENT=jsonv2)
- **runtime/trace.FlightRecorder**: Production trace capture on-demand
- **Container-aware GOMAXPROCS**: Auto-detects cgroup limits
- **GreenTea GC**: Experimental, lower latency (GOEXPERIMENT=greenteagc)

## References

- [PATTERNS.md](PATTERNS.md) - Detailed code patterns
- [TESTING.md](TESTING.md) - Testing strategies with testify/mockery
- [CLI.md](CLI.md) - CLI application patterns

## Tooling

```bash
go build ./...           # Build
go test -race ./...      # Test with race detector
golangci-lint run        # Lint
mockery --all            # Generate mocks
```

---

## Gotchas

- **`nil` channel sends/receives block forever; closed channel receives return zero value immediately** — `select` with a nil channel case disables that case, useful pattern but easy to do accidentally.
- **`defer` captures arguments at the call site, not at execution** — `defer fmt.Println(time.Now())` captures NOW, not the deferred time.
- **Pre-Go 1.22 for-loop variable capture closures over ONE variable across all iterations** — the goroutine-in-loop bug. Go 1.22 changed semantics; old habits create subtle bugs in mixed-version code.
- **`errors.Is` walks `Unwrap()` chains, BUT if a wrapped error implements `Is(target error) bool` itself, that custom Is wins over walking** — confusing when migrating from xerrors.
- **`sync.Pool` items can be GC'd between `Get` and the next `Put`** — never rely on a Pool to retain state.

© julianobarbosa · MIT · julianobarbosa/claude-code-skills

Similar skills

All skills for Programming languages →

From the same set37

The whole set →
context7 Look up version-specific library documentation and code examples through Context7. Use it before coding against an API or framework behavior you’re unsure about. CX Codex +1 114installs git-worktree Automates git worktree workflows with tmux windows and iTerm2 tabs. Helps run isolated feature branches and parallel Claude Code sessions. CX Codex +1 111installs writing-typescript writing-typescript — a TypeScript skill for Node.js services, React apps, and TS pattern discussions. It favors strict typing, composition, and a toolchain built around bun and vite. CX Codex +1 111installs az-aks-agent az-aks-agent is a Claude Code skill that investigates Azure Kubernetes Service cluster health and configuration. It examines pod, networking, storage, and RBAC issues. CX Codex +1 110installs macos-cleaner The macos-cleaner skill examines disk usage on a Mac and suggests cleanup options. Use it to find what is taking up space and weigh the effects of removing it. CX Codex +1 109installs knative knative guides Kubernetes serverless deployments, scale-to-zero autoscaling, traffic splitting, and CloudEvents routing. CX Codex +1 109installs pyroscope Guides and configs for Grafana Pyroscope continuous profiling: Helm deployments, Go/Java/Python SDK setups, object storage, and trace correlation. CX Codex +1 108installs using-cloud-cli The using-cloud-cli skill sets patterns for bq, gcloud, and aws. Use it for BigQuery queries, cloud resource commands, and AWS or GCP service decisions. CX Codex +1 108installs

Project sponsors

Companies that keep this analytics open