go-benchmark
Measure and compare Go benchmarks or profiles; not PR review or optimization.
SKILL.mdagent-plugins/skills/go-benchmark/SKILL.md
GitHubGo Benchmark
Measure a named Go behavior under controlled conditions. Return evidence for a performance claim rather than assuming that fewer allocations or shorter code makes the product faster.
Route precisely
- Use when asked to design/write a benchmark, measure a hot path, interpret an existing profile, or compare named implementations.
- Use
code-reviewfor potential defects in a diff,debugging-and-error-recoveryfor an unexplained failing or hanging program, andprove-checksfor whether a passing check can detect its claimed defect. - Keep production optimization, dependency installation, release publication, and CI authoring outside this workflow unless separately requested. Do not launch agents or create worktrees automatically.
Establish the experiment
- Read repository instructions, working-tree state,
go.mod/go.work, benchmark source, and callers. Record revision/local changes, supported Go version, actual toolchain, OS/architecture, hardware, GOMAXPROCS, build flags/tags, data size, and relevant dependency/configuration versions. - Name the operation, representative workload, metric, desired decision, and correctness invariant. Separate microbenchmark throughput/allocations from end-to-end latency or a product requirement. If target, fixture, or baseline is unknown, resolve it before expensive measurement.
- Inspect benchmark setup, timed work, input reuse, result consumption, parallelism, and possible compiler elimination. Use version-supported APIs;
b.Looprequires a supporting toolchain. Keep setup outside timed work only when setup is outside the operation being claimed. - Reuse existing benchmarks first. Write or change benchmark files only when requested or necessary within an authorized benchmark-writing task; otherwise propose the change. Do not modify production code to create a faster result.
Measure within a budget
Agree the measurement scope from the request and project conventions: named packages/cases, run count, duration, profile type, and artifact destination. Use a disposable output location and preserve the working checkout. Inspect any benchmark or setup that may contact services or modify data before running it; isolate side effects.
Select the exact benchmark and avoid unrelated tests when supported. For example, adapt go test -run '^$' -bench '^BenchmarkParse$' -benchmem -count=10 <package> to the actual package and budget; do not run this example literally with a placeholder. Verify that the intended benchmark emitted measurements. No matches, missing tools, skipped work, or a failed run is not a measured pass.
Run competing measurements serially on the same hardware and toolchain with the same fixture, settings, and benchmark harness. Preserve the exact baseline input and record order, warmup/cache state, and shared-machine noise. Re-measure the baseline under matching conditions when an old report used a different toolchain, machine, or workload. Do not attribute toolchain or fixture differences to the implementation.
Compare and diagnose
Use an existing version-identified benchstat or an equivalent documented analysis; do not install or upgrade it automatically. Compare repeated samples and report sample count, variance/uncertainty, statistical evidence when available, and effect size. A small p-value alone does not establish a practically useful improvement; an inconclusive result is valid.
Read references/measurement-checks.md for harness validity, profiles, and comparison pitfalls. Profile only the relevant workload and protect artifacts that may contain paths, symbols, or user data. Do not open a production profiling endpoint or expose a new one as a side effect of measurement.
If an optimization is later authorized, change one hypothesis at a time, verify the correctness invariant, and compare against the same baseline. Do not commit results, choose a winner automatically, or claim unchanged behavior from benchmark timing alone.
Report
Return the question and metric, run identities/environment, baseline and candidate definitions, exact commands and selected cases, correctness evidence, sample summary and uncertainty, artifact locations, unrun work, and limits.
Use one outcome: MEASURED_DIFFERENCE, NO_CLEAR_DIFFERENCE, or INCOMPARABLE. State direction and practical impact for a measured difference. Use INCOMPARABLE for mismatched environments/harnesses, empty selection, missing baseline, or invalid execution. Do not invent missing values or claim speedups from a single timing or a static code inspection.
Adapted and substantially rewritten from Samber's golang-benchmark and measurement guidance in golang-performance, under the bundled LICENSE.samber-cc-skills-golang.