go-style-guide — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited go-style-guide (Agent Skill) and scored it 96/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 1 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 1 flagged
The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
This skill defines practical Go engineering conventions for humans, coding agents, and production-ready systems.
Use this skill whenever you are working with Go: new code, refactors, reviews, architecture decisions, package design, or test strategy.
Config in -> concrete struct out; validate, default, and documentimportant runtime knobs.
%w or errors.Join.
side effects.
must earn their weight through meaningful, maintained, adopted abstraction.
happy paths.
interfaces, shared contract packages are a special case.
main.go thin; follow existing repo layout conventions rather thanforcing one directory shape.
-race.
and doc comments; they are as important as the code itself.
This is intentionally opinionated. It favors consistency and long-term maintainability over accommodating every Go style preference. If the target repo has clear local conventions, those conventions usually win.
Examples assume modern Go and use standard-library features such as errors.Join and log/slog. Apply the guide within the constraints of the target repository's supported Go version.
Follow this workflow when using the skill for implementation work:
Read existing package layout, constructors, tests, and error conventions before proposing new APIs or moving files.
Decide the package boundary, config shape, concrete return type, sentinel errors, dependency seams, and context or shutdown expectations up front.
Start with table-driven unit tests, add fuzz tests for parsing or other input-heavy code, and add benchmarks for performance-sensitive paths.
Follow the repository's existing layout, keep main.go thin, and avoid introducing new abstractions without a clear boundary.
Format with gofmt (and goimports if the repo uses it), run the relevant go test targets, run go test -race when concurrency is involved, and run benchmarks when claiming performance improvements.
Make sure docs, comments, config defaults, and error behavior match the code you are shipping.
| Topic | Rule | Reference |
|---|---|---|
| Testability | Design for confidence, not coverage percentages; test edge and misuse cases | references/TESTING.md |
| Constructors | Config in -> concrete struct out; validate + default in New; use Config.Validate() when config logic grows | references/CONFIG.md |
| Errors | Use sentinels for durable branching; wrap with %w or errors.Join; keep recover at app boundaries | references/ERRORS.md |
| Logging | Packages do not log by default; hot-path logging is a performance decision | references/LOGGING.md |
| Dependencies | Standard library first; add third-party packages only when they provide meaningful, maintained value | references/LAYOUT.md |
| Interfaces | "Accept interfaces, return structs"; consumers usually define interfaces | references/INTERFACES.md |
| Documentation | Write idiomatic godoc and durable comments; never add agent-context comments | references/DOCUMENTATION.md |
| Layout | Keep packages shallow, avoid junk drawers, and follow repo conventions | references/LAYOUT.md |
| Entry Points | main.go is wiring only | references/LAYOUT.md |
| Benchmarks | Benchmark hot paths; use b.ReportAllocs() and compare runs with benchstat | references/BENCHMARKS.md |
| Testing | Table-driven, stdlib-first, defensive against misuse, and fuzz-heavy where inputs are complex | references/TESTING.md |
| Concurrency | Every goroutine needs a shutdown path; use context.Context, -race, and jitter where needed | references/CONCURRENCY.md |
| Reviews | Use the checklist when reviewing Go changes | references/REVIEW-CHECKLIST.md |
clear enough.
Config.conventions.
concurrency safety without -race.
Load reference files only when the task needs that topic's detail.
metrics policy.
Config or Opts, acceptinitialized dependencies, and avoid hidden logging or global state.
third-party package only when it solves a real problem, is actively maintained, and earns its transitive cost.
cmd/<appname>/main.go thin. Follow established repolayout over forcing pkg/, internal/, or any house shape.
New(cfg Config) (*T, error), explicit defaults,validation, concrete returns, and immutable normalized config.
-racefor concurrency-sensitive code.
the contract.
Load only the references needed for the active task:
Config structs, defaults, validation, degraded modes, or logging injection.
boundaries, driver patterns, mocks/fakes, or concrete return decisions.
wrapping, typed errors, recover placement, or constructor failures.
slog, log levels, async error surfaces, or payload safety.
fuzzing, testdata, integration gates, test helpers, or assertion choices.
context propagation, graceful shutdown, mutex/atomic/channel choices, jitter, or race testing.
naming, main.go, dependency hygiene, struct field layout, or export rules.
docs, godoc, examples, deprecations, internal comments, or field docs.
shape, allocation reporting, concurrent benchmarks, IO benchmarks, or benchstat.
reviewing a Go PR or doing a final self-check.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.