---
name: go-package-documenter
description: "Reference documentation for a Go package that reads like good pkg.go.dev material: an overview, an API reference with every exported symbol explained, runnable examples, and a version note, in Markdown or HTML. Use when a Go package needs reference docs or a README-style API guide written from its exported functions and types, with examples that compile. Do not use for writing the inline doc comments inside the source, or documenting a REST or GraphQL API. Related topics: coding, package."
---

# Go Package Documenter

Reference documentation for a Go package that reads like good pkg.go.dev material: an overview, an API reference with every exported symbol explained, runnable examples, and a version note, in Markdown or HTML.

## When to use

Use this skill when a Go package needs reference docs or a README-style API guide written from its exported functions and types, with examples that compile. Do not use it for writing the inline doc comments inside the source, or documenting a REST or GraphQL API.

## 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. Write the overview naming the package's purpose, its main entry point, and what it does not do, in three to five sentences.
3. Document each exported symbol with signature, a go doc style first sentence, parameters, return values, every error, and any concurrency rule, grouped by owning type.
4. Write runnable examples for the common path and one error path that compile against the listed signatures, when examples are on.
5. Adjust depth per audience selected: getting-started path, stability and error contract, or configuration and observability notes.
6. Close with the version note and compatibility line, and mark any symbol lacking information with a TODO rather than a guess.

## Inputs

- **Package name and import path** (free text, e.g. "ratelimit (github.com/acme/ratelimit)")
- **Exported symbols** (longer free text)
- **Documentation tone** (choose one: Formal, Friendly, Concise)
- **Include usage examples** (choose one: Yes, No)
- **Target audience** (choose any: Junior developers, Senior engineers, API consumers, DevOps)
- **Output format** (choose one: Markdown, HTML)
- **Version tag** (free text, e.g. "v1.2.0")

## Output

A single document in the chosen format with sections Overview, API Reference (grouped by type), Examples when enabled, and Version, each symbol as a heading with its signature in a code block.

## Prompt template

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

### Go Package Documenter

Write the reference documentation for my Go package.

#### Details
- Package name and import path: {{Package name and import path}}
- Exported symbols: {{Exported symbols}}
- Documentation tone: {{Documentation tone}}
- Include usage examples: {{Include usage examples}}
- Target audience: {{Target audience}}
- Output format: {{Output format}}
- Version tag: {{Version tag}}

Open with an overview that states what the package is for, the one type or function most users start with, and what it deliberately does not do. Document every exported symbol in the API reference with its signature, a sentence that begins with the symbol name as go doc convention expects, the parameters and return values including every error it can return, and any concurrency or lifetime rules (safe for concurrent use, must be closed). Group symbols by the type they belong to: constructor first, then methods, then package-level functions. When examples are on, write runnable snippets that compile against the listed signatures and show the common path and one error path. Pitch the depth to the audience: juniors get a short getting-started path, API consumers get the stability and error contract, DevOps get configuration and observability notes. Close with the version note and a one-line compatibility promise. Document only the symbols listed and mark any gap with a short TODO, so nothing invented reaches the docs.

## Pitfalls

- Starting a symbol's description with 'This function' instead of the symbol name, which breaks the go doc convention readers expect.
- Listing the happy path only and leaving out the errors a function returns, which is the part consumers actually need.
- Documenting symbols that were not supplied, which produces confident references to code that does not exist.
