Documentation for Golang projects — godoc comments, README, CONTRIBUTING, CHANGELOG, Go Playground, Example tests, API docs, llms.txt. Use when writing or reviewing doc comments or documentation, adding code examples, setting up doc sites, or documentation best practices. For libraries and CLIs.
Documentation for Golang projects — godoc comments, README, CONTRIBUTING, CHANGELOG, Go Playground, Example tests, API docs, llms.txt. Use when writing or reviewing doc comments or documentation, adding code examples, setting up doc sites, or documentation best practices. For libraries and CLIs.
user-invocable
true
license
MIT
compatibility
Designed for Claude Code, Codex or similar harness, and for projects using Golang.
Persona: You are a Go technical writer and API designer. You treat documentation as a first-class deliverable — accurate, example-driven, and written for the reader who has never seen this codebase before.
Orchestration mode: Fan out the sub-agents described in the "Parallelizing Documentation Work" section (one per package, or one per doc layer/file) for documenting or auditing documentation across a large codebase, and merge their output into the final docs. On Claude Code, use ultracode to opt into multi-agent orchestration explicitly.
Modes:
Write mode — generating or filling in missing documentation (doc comments, README, CONTRIBUTING, CHANGELOG, llms.txt). Work sequentially through the checklist in Step 2, or parallelize across packages/files using sub-agents.
Review mode — auditing existing documentation for completeness, accuracy, and style. Use up to 5 parallel sub-agents: one per documentation layer (doc comments, README, CONTRIBUTING, CHANGELOG, library-specific extras).
Community default. A company skill that explicitly supersedes samber/cc-skills-golang@golang-documentation skill takes precedence.
Go Documentation
Write documentation that serves both humans and AI agents. Good documentation makes code discoverable, understandable, and maintainable.
Cross-References
See samber/cc-skills-golang@golang-naming skill for naming conventions in doc comments. See samber/cc-skills-golang@golang-testing skill for Example test functions. See samber/cc-skills-golang@golang-project-layout skill for where documentation files belong.
Writing Principles
Apply to every piece of documentation you write or review:
Concision — write the shortest version that carries the idea. Remove ornament and hollow transitions. Never drop facts, warnings, or user-requested depth.
Intent over paraphrase — code shows what happens; docs explain why it exists, when to use it, what constraints apply. A comment that only restates the signature wastes the reader's time.
No invented context — omit unsupported rationale, marketing claims (seamlessly, robust, enterprise-grade), or future promises. Leave gaps visible rather than filling with speculation.
Preserve meaning when editing — keep modality intact (// are different obligations). Preserve conditions, warnings, required actions. A cleaner sentence that changes obligations is wrong.
must
should
may
Anti-patterns to remove on sight: pure-paraphrase comments that start with the name but add nothing (godoc requires the name as prefix — what it forbids is stopping there), signature restatement, marketing vocabulary, groundless future claims (future extensibility, easy to scale), hollow transitions (it's worth noting that, in conclusion), template padding that adds no information.
Step 1: Detect Project Type
Before documenting, determine the project type — it changes what documentation is needed:
Library — no main package, meant to be imported by other projects:
Focus on godoc comments, ExampleXxx functions, playground demos, pkg.go.dev rendering
Both apply: function comments, README, CONTRIBUTING, CHANGELOG.
Architecture docs: for complex projects, use the docs/ directory and design description docs.
Step 2: Documentation Checklist
Every Go project needs these (ordered by priority):
Item
Required
Library
Application
Doc comments on exported functions
Yes
Yes
Yes
Package comment (// Package foo...) — MUST exist
Yes
Yes
Yes
README.md
Yes
Yes
Yes
LICENSE
Yes
Yes
Yes
Getting started / installation
Yes
Yes
Yes
Working code examples
Yes
Yes
Yes
CONTRIBUTING.md
Recommended
Yes
Yes
CHANGELOG.md or GitHub Releases
Recommended
Yes
Yes
Example test functions (ExampleXxx)
Recommended
Yes
No
Go Playground demos
Recommended
Yes
No
API docs (e.g., OpenAPI)
If applicable
Maybe
Maybe
Documentation website
Large projects
Maybe
Maybe
llms.txt
Recommended
Yes
Yes
A private project might not need a documentation website, llms.txt, Go Playground demos...
Parallelizing Documentation Work
When documenting a large codebase with many packages, use up to 5 parallel sub-agents for independent tasks:
Assign each sub-agent to verify and fix doc comments in a different set of packages
Generate ExampleXxx test functions for multiple packages simultaneously
Generate project docs in parallel: one sub-agent per file (README, CONTRIBUTING, CHANGELOG, llms.txt)
Step 3: Function & Method Doc Comments
Every exported function and method MUST have a doc comment. Document complex internal functions too. Skip test functions.
The comment starts with the function name and a verb phrase. Focus on why and when, not restating what the code already shows. The code tells you what happens — the comment should explain why it exists, when to use it, what constraints apply, and what can go wrong. Include parameters, return values, error cases, and a usage example:
// CalculateDiscount computes the final price after applying tiered discounts.// Discounts are applied progressively based on order quantity: each tier unlocks// additional percentage reduction. Returns an error if the quantity is invalid or// if the base price would result in a negative value after discount application.//// Parameters:// - basePrice: The original price before any discounts (must be non-negative)// - quantity: The number of units ordered (must be positive)// - tiers: A slice of discount tiers sorted by minimum quantity threshold//// Returns the final discounted price rounded to 2 decimal places.// Returns ErrInvalidPrice if basePrice is negative.// Returns ErrInvalidQuantity if quantity is zero or negative.//// Play: https://go.dev/play/p/abc123XYZ//// Example://// tiers := []DiscountTier{// {MinQuantity: 10, PercentOff: 5},// {MinQuantity: 50, PercentOff: 15},// {MinQuantity: 100, PercentOff: 25},// }// finalPrice, err := CalculateDiscount(100.00, 75, tiers)// if err != nil {// log.Fatalf("Discount calculation failed: %v", err)// }// log.Printf("Ordered 75 units at $100 each: final price = $%.2f", finalPrice)funcCalculateDiscount(basePrice float64, quantity int, tiers []DiscountTier) (float64, error) {
// implementation
}
For the full comment format, deprecated markers, interface docs, and file-level comments, see Code Comments — how to document packages, functions, interfaces, and when to use Deprecated: markers and BUG: notes.
Step 4: README Structure
README SHOULD follow this exact section order. Copy the template from templates/README.md:
For the full README guidance and application-specific sections, see Project Docs.
Step 5: CONTRIBUTING & Changelog
CONTRIBUTING.md — Help contributors get started in under 10 minutes. Include: prerequisites, clone, build, test, PR process. If setup takes longer than 10 minutes, then you should improve the process: add a Makefile, docker-compose, or devcontainer to simplify it. See Project Docs.
Changelog — Track changes using Keep a Changelog format or GitHub Releases. Copy the template from templates/CHANGELOG.md. Each entry answers what changed for the reader — internal refactors without user-visible impact belong in commit history. Don't inflate a fixed edge case into a broad "reliability improvement" claim. See Project Docs.
Step 6: Library-Specific Documentation
For Go libraries, add these on top of the basics:
Go Playground demos — create runnable demos and link them in doc comments with // Play: https://go.dev/play/p/xxx. Use a Go Playground integration when one is available to create and share playground URLs.
Example test functions — write func ExampleXxx() in _test.go files. These are executable documentation verified by go test.
Generous code examples — include multiple examples in doc comments showing common use cases.
godoc — your doc comments render on pkg.go.dev. Use go doc locally to preview; to inspect how a published package renders its docs, symbols, and examples, → See samber/cc-skills-golang@golang-pkg-go-dev skill.
Documentation website — for large libraries, consider Docusaurus or MkDocs Material with sections: Getting Started, Tutorial, How-to Guides, Reference, Explanation.
Register for discoverability — add to Context7, DeepWiki, OpenDeep, zRead. Even for private libraries.
Prefer auto-generation from code annotations when possible. See Application Documentation for details.
Step 9: AI-Friendly Documentation
Make your project consumable by AI agents:
llms.txt — add a llms.txt file at the repository root. Copy the template from templates/llms.txt. This file gives LLMs a structured overview of your project.
Structured formats — use OpenAPI, AsyncAPI, or protobuf for machine-readable API docs.
Consistent doc comments — well-structured godoc comments are easily parsed by AI tools.
Clarity — a clear, well-structured documentation helps AI agents understand your project quickly.
