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
npx skills add julianobarbosa/claude-code-skills --skill writing-go -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/writing-go/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/writing-go/
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill writing-go -a codex2Manually: put the files in place
.agents/skills/writing-go/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill writing-go -a cursor2Manually: put the files in place
.cursor/skills/writing-go/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install julianobarbosa/claude-code-skills skills/writing-go2Manually: put the files in place
.github/skills/writing-go/SKILL.md1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill writing-go -a gemini-cli2Platform CLI
gemini skills install https://github.com/julianobarbosa/claude-code-skills --path skills/writing-goManually: put the files in place
.devin/skills/writing-go/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill writing-go -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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