---
name: go-package-builder
description: "A compilable Go module skeleton: go.mod pinned to your Go version, an idiomatic package layout, a starter source file with doc comments, a README, and a passing table-driven test when you want one. Use when starting a new Go module or package from nothing and wanting go.mod, layout, starter code, README, and a first test that already pass go build and go test. Do not use for restructuring an existing Go codebase, or debugging a package that fails to compile. Related topics: coding, package."
---

# Go Package Builder

A compilable Go module skeleton: go.mod pinned to your Go version, an idiomatic package layout, a starter source file with doc comments, a README, and a passing table-driven test when you want one.

## When to use

Use this skill when starting a new Go module or package from nothing and wanting go.mod, layout, starter code, README, and a first test that already pass go build and go test. Do not use it for restructuring an existing Go codebase, or debugging a package that fails to compile.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Pick the directory layout from the module kind (library root, cmd directory, internal) so nothing importable leaks that should stay private.
3. Write go.mod with the module path, go directive, and only the selected dependencies at current stable versions.
4. Write the starter source file with a package doc comment, one exported type and constructor, and a doc comment on every exported identifier.
5. Add the table-driven test and a compiling Example function when the test is enabled, using the selected test library.
6. Write the README with install, a usage snippet that matches the real API, and the license, then confirm every file compiles together.

## Inputs

- **Module path** (free text, e.g. "github.com/acme/ratelimit")
- **Package name** (free text, e.g. "ratelimit")
- **What the package does** (longer free text)
- **Go version** (choose one: 1.21, 1.22, 1.23, 1.24)
- **License** (choose one: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, Unlicense)
- **Dependencies** (choose any: github.com/stretchr/testify, golang.org/x/sync, github.com/google/uuid, log/slog only, none)
- **Kind of module** (choose one: Library package only, Library with a cmd binary, CLI tool)
- **Include an example test** (choose one: Yes, No)

## Output

One markdown response with a file list, then each file as a path line followed by a fenced code block, ordered go.mod, source, test, README, and a license note.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Go Package Builder

Scaffold a new Go module that builds and tests cleanly on the first run.

#### Details
- Module path: {{Module path}}
- Package name: {{Package name}}
- What the package does: {{What the package does}}
- Go version: {{Go version}}
- License: {{License}}
- Dependencies: {{Dependencies}}
- Kind of module: {{Kind of module}}
- Include an example test: {{Include an example test}}

Choose the layout from the kind of module: a library keeps its code at the module root under the package name, a binary adds a cmd directory with its own main.go that imports the library, and internal holds anything that must not be imported from outside. Write go.mod with the module path, the go directive, and only the dependencies selected. In the starter file, define the main exported type and constructor with a package doc comment and a doc comment on every exported identifier, since go doc and pkg.go.dev read them. Keep the API small: one constructor, one or two methods, errors returned as values. When the test is on, write a table-driven test for the main method using the selected test library or the standard library when none, and an Example function that compiles. Add a README with install, a usage snippet that matches the real API, and the license line. Every file must compile together, with go build ./... and go test ./... passing.

## Pitfalls

- Putting code in a pkg or src directory out of habit, which is not idiomatic and makes import paths longer for no gain.
- Writing a README usage snippet that calls a function the starter file never defines.
- Naming the package util or common, which says nothing to importers and collides with other modules.
