Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
AI & knowledge

golang-documentation

Comprehensive documentation guide for Golang projects, covering godoc comments, README, CONTRIBUTING, CHANGELOG, Go Playground, Example tests, API docs, and llms.txt. Use when writing or reviewing doc comments, documentation, adding code examples, setting up doc sites, or discussing documentation best practices. Triggers for both libraries and applications/CLIs.

samber · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add samber/cc-skills-golang --skill golang-documentation

About this skill


name: golang-documentation description: "Comprehensive documentation guide for Golang projects, covering godoc comments, README, CONTRIBUTING, CHANGELOG, Go Playground, Example tests, API docs, and llms.txt. Use when writing or reviewing doc comments, documentation, adding code examples, setting up doc sites, or discussing documentation best practices. Triggers for both libraries and applications/CLIs." user-invocable: true license: MIT compatibility: Designed for Claude Code, Codex or similar harness, and for projects using Golang. metadata: author: samber version: "1.2.0" openclaw: emoji: "📝" homepage: https://github.com/samber/cc-skills-golang requires: bins: - go install: [] allowed-tools: Read Edit Write Glob Grep Bash(go:) Bash(golangci-lint:) Bash(git:*) Agent WebFetch paths:

  • "**/*.go"

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 (must/should/may are different obligations). Preserve conditions, warnings, required actions. A cleaner sentence that changes obligations is wrong.

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
  • See Library Documentation

Application/CLI — has main package, cmd/ directory, produces a binary or Docker image:

  • Focus on installation instructions, CLI help text, configuration docs
  • See Application Documentation

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):

ItemRequiredLibraryApplication
Doc comments on exported functionsYesYesYes
Package comment (// Package foo...) — MUST existYesYesYes
README.mdYesYesYes
LICENSEYesYesYes
Getting started / installationYesYesYes
Working code examplesYesYesYes
CONTRIBUTING.mdRecommendedYesYes
CHANGELOG.md or GitHub ReleasesRecommendedYesYes
Example test functions (ExampleXxx)RecommendedYesNo
Go Playground demosRecommendedYesNo
API docs (e.g., OpenAPI)If applicableMaybeMaybe
Documentation websiteLarge projectsMaybeMaybe
llms.txtRecommendedYesYes

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 functio

Read the complete source ↗