Skip to main content
ZICQ

Skills ZICQ category:Documents golang-documentation

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.

42621 installs

Official URL:Author homepage

What this skill does

Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.

What it does

Comprehensive documentation guide for Golang projects, covering godoc comments, README, CONTRIBUTING, CHANGELOG, Go Playground, Example tests, API docs, and llms.txt

When to use it

`Deprecated:` markers and `BUG:` notes

How agents load it

Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: Go Documentation; Cross-References; Writing Principles; Step 1: Detect Project Type; Step 2: Documentation Checklist; Parallelizing Documentation Work. It includes spec-recommended sections: step-by-step instructions.

File analysis

File analysis: besides SKILL.md, the body references references/library.md, references/application.md, references/code-comments.md, assets/templates/README.md, references/project-docs.md, assets/templates/CHANGELOG.md. Those resources load on demand.

Go DocumentationCross-ReferencesWriting PrinciplesStep 1: Detect Project TypeStep 2: Documentation ChecklistParallelizing Documentation WorkStep 3: Function & Method Doc CommentsStep 4: README StructureStep 5: CONTRIBUTING & ChangelogStep 6: Library-Specific DocumentationStep 7: Application-Specific DocumentationStep 8: API Documentation

Compatibility:Designed for Claude Code, Codex or similar harness, and for projects using Golang. · License:MIT · allowed-tools:Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent WebFetch

Source category:skills.sh agent-skill

SKILL.md & Agent activation

Official spec ↗
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.
compatibility
Designed for Claude Code, Codex or similar harness, and for projects using Golang.
allowed-tools
Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent WebFetchExperimental field; support depends on the client and does not grant permissions by itself.
License
MIT
  1. DiscoverThe client exposes names and descriptions to the agent.
  2. ActivateYour request or the task context selects the skill and loads its instructions.
  3. Load resourcesReferenced scripts, documentation and assets are used when needed.
Files referenced by the instructions · 7
  • references/library.md
  • references/application.md
  • references/code-comments.md
  • assets/templates/README.md
  • references/project-docs.md
  • assets/templates/CHANGELOG.md
  • assets/templates/llms.txt

These paths are extracted from the text. Check the upstream package to verify the files exist.

Invocation syntax and available tools depend on your Agent client. Client integration guide ↗

Install this skill

Skills CLI ↗

Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.

This skill references supporting files. Retrieve the complete directory from the source; copying SKILL.md alone may leave missing dependencies.

Ask your Agent to install

Copy these instructions to a compatible agent and confirm the target directory matches your client.

Install the agent skill "golang-documentation" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-0b872b025b3cd17b-Golang-Documentation.html
Save it as .cursor/skills/golang-documentation/SKILL.md or .claude/skills/golang-documentation/SKILL.md and keep the frontmatter name and description exactly as-is.
This skill also ships scripts/, references/, or assets/ — fetch the whole folder from https://github.com/samber/cc-skills-golang instead of creating only a SKILL.md.

Full package on GitHub ↗

Install from the terminal · Skills CLI

Requires Node.js and npx. First inspect the repository's skill list to confirm the name.

npx skills add 'https://github.com/samber/cc-skills-golang' --list

npx skills add 'https://github.com/samber/cc-skills-golang' --skill 'golang-documentation'

The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.

Readable layout

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.3.2" 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.
  • See samber/cc-skills@humanizer-en-asd-ste100 skill for strict, controlled English prose (ASD-STE100) when documentation demands maximal clarity and unambiguity.

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.

For regulated or safety-critical documentation that requires strict controlled-English prose, → See samber/cc-skills@humanizer-en-asd-ste100 skill.

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:

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)
func CalculateDiscount(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:

  1. Title — project name as # heading
  2. Badges — shields.io pictograms (Go version, license, CI, coverage, Go Report Card...)
  3. Summary — 1-2 sentences explaining what the project does
  4. Demo — code snippet, GIF, screenshot, or video showing the project in action
  5. Getting Started — installation + minimal working example
  6. Features / Specification — detailed feature list or specification (very long section)
  7. Contributing — link to CONTRIBUTING.md or inline if very short
  8. Contributors — thank contributors (badge or list)
  9. License — license name + link

Common badges for Go projects:

[![Go Version](https://img.shields.io/github/go-mod/go-version/{owner}/{repo})](https://go.dev/) [![License](https://img.shields.io/github/license/{owner}/{repo})](./LICENSE) [![Build Status](https://img.shields.io/github/actions/workflow/status/{owner}/{repo}/test.yml?branch=main)](https://github.com/{owner}/{repo}/actions) [![Coverage](https://img.shields.io/codecov/c/github/{owner}/{repo})](https://codecov.io/gh/{owner}/{repo}) [![Go Report Card](https://goreportcard.com/badge/github.com/{owner}/{repo})](https://goreportcard.com/report/github.com/{owner}/{repo}) [![Go Reference](https://pkg.go.dev/badge/github.com/{owner}/{repo}.svg)](https://pkg.go.dev/github.com/{owner}/{repo})

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, covering prerequisites, clone, build, test, and PR process. If setup takes longer, improve the process with a Makefile, docker-compose, or devcontainer. See Project Docs.

Changelog — Track changes using Keep a Changelog format or GitHub Releases, copying the template from templates/CHANGELOG.md. Write each entry to answer what changed for the reader — internal refactors without user-visible impact belong in commit history, and a fixed edge case never becomes 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.

See Library Documentation for details.

Step 7: Application-Specific Documentation

For Go applications/CLIs:

  • Installation methods — pre-built binaries (GoReleaser), go install, Docker images, Homebrew...
  • CLI help text — make --help comprehensive; it's the primary documentation
  • Configuration docs — document all env vars, config files, CLI flags

See Application Documentation for details.

Step 8: API Documentation

If your project exposes an API:

| API Style | Format | Tool | | ------------ | ----------- | -------------------------------------------- | | REST/HTTP | OpenAPI 3.x | swaggo/swag (auto-generate from annotations) | | Event-driven | AsyncAPI | Manual or code-gen | | gRPC | Protobuf | buf, grpc-gateway |

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.

Step 10: Delivery Documentation

Document how users get your project:

Libraries:

go get github.com/{owner}/{repo}

Applications:

# Pre-built binary
curl -sSL https://github.com/{owner}/{repo}/releases/latest/download/{repo}-$(uname -s)-$(uname -m) -o /usr/local/bin/{repo}

# From source
go install github.com/{owner}/{repo}@latest

# Docker
docker pull {registry}/{owner}/{repo}:latest

See Project Docs for Dockerfile best practices and Homebrew tap setup.

Related skills

Documents

Ontology

Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, …

Documents

Nano Pdf

Edit PDFs with natural-language instructions using the nano-pdf CLI.

Documents

Word / DOCX

Create, inspect, and edit Microsoft Word documents and DOCX files with reliable styles, numbering, tracked changes, tables, sections, and co…

Documents

Api Gateway

Call third-party APIs through the Maton gateway, which injects the credential for an app the user has already connected. Use this skill when…