oioio-space/unpixel / .claude/skills/go-style-guide
go-style-guide
VerifiedUse when writing, reviewing, or committing ANY Go code in this project — enforces the three Google Go Style Guides (guide, decisions, best-practices) item by item.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.4 KB |
| references/best-practices.md | markdown | 8.0 KB |
| references/decisions.md | markdown | 7.0 KB |
| references/guide.md | markdown | 2.6 KB |
SKILL.md
View on GitHub---
name: go-style-guide
description: Use when writing, reviewing, or committing ANY Go code in this project — enforces the three Google Go Style Guides (guide, decisions, best-practices) item by item.
---
# Google Go Style Guide
This project follows the three Google Go style documents. This skill enforces them
item by item, in two layers:
- **Deterministic layer** — `golangci-lint` + `gofmt`, run by the git `pre-commit`
hook (`.githooks/pre-commit` → `scripts/lint.sh`). Covers objective items.
- **AI-review layer** — when you (Claude) are about to `git commit`, the
PreToolUse hook injects `scripts/style-checklist.md` and you MUST confront the
staged diff against EVERY item before committing. Covers subjective items
(naming quality, comment usefulness, simplicity).
## The five principles (priority order)
From `references/guide.md`. When principles conflict, earlier wins:
1. **Clarity** — the code's purpose and rationale are clear to the reader.
2. **Simplicity** — simplest way to accomplish the goal; least mechanism.
3. **Concision** — high signal-to-noise ratio; no repetition or noise.
4. **Maintainability** — code is edited far more than written; design for change.
5. **Consistency** — looks/behaves like the surrounding codebase (tie-breaker).
## How to use this skill
- **Writing code** → keep the principles above in mind; consult the relevant
`references/*.md` when unsure about a specific decision (naming, errors, tests…).
- **Reviewing a diff / before committing** → walk `scripts/style-checklist.md`
top to bottom against the diff. It is the single source of truth for the AI layer.
## Reference files (load on demand)
- `references/guide.md` — core principles & formatting rules (the "why").
- `references/decisions.md` — itemized normative decisions: naming, commentary,
imports, errors, language constructs, common libraries, test failures.
- `references/best-practices.md` — itemized patterns: naming, errors (`%w` vs `%v`,
structured/sentinel errors), documentation, variable declarations, option
patterns, and testing.
## Most-checked items (quick reference)
- `MixedCaps`, never `under_scores`; initialisms keep case (`URL`, `ID`, `userID`).
- Exported symbols have doc comments starting with the symbol name, full sentences
ending in a period.
- **GoDoc / pkg.go.dev**: write exported docs to render well on pkg.go.dev, not just
to exist. Document every exported struct field / interface method / const-var
individually; give the package doc a real overview (what + approach + how to use,
with a usage snippet); state contracts (zero-value/default behavior, channel/resource
ownership, nil handling, which error when); add a runnable `Example` (in `pkg_test`)
for public packages so usage shows on pkg.go.dev. Sanity-check with `go doc ./<pkg>`.
- Error strings: lowercase, no trailing punctuation. Wrap with `%w` (at the end)
when callers need `errors.Is`/`errors.As`; `%v` at system boundaries.
- Handle errors immediately; indent the error path, keep the happy path un-indented;
avoid `else` after a returning `if`.
- No `Get` prefix on getters. Receiver names are 1–2 letters, consistent per type.
- No `util`/`helper`/`common` package names. Don't shadow stdlib package names.
- Tests: `got` before `want`; identify function + inputs in failures; `t.Error`
to keep going, `t.Fatal` only when continuing is meaningless; field names in
table-driven struct literals; never `t.Fatal` from a spawned goroutine.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |