From golang-skills
Guides writing and reviewing documentation for Go packages, types, functions, and methods per Google Style Guide. Validates missing doc comments on exported symbols via bash script.
npx claudepluginhub cxuu/golang-skills --plugin golang-skillsThis skill is limited to using the following tools:
- **`scripts/check-docs.sh`** — Reports exported functions, types, methods, constants, and packages missing doc comments. Run `bash scripts/check-docs.sh --help` for options.
Generates and reviews Go project documentation including godoc comments, README, CONTRIBUTING, CHANGELOG, examples, playground demos, and API docs for libraries and CLIs.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
scripts/check-docs.sh — Reports exported functions, types, methods, constants, and packages missing doc comments. Run bash scripts/check-docs.sh --help for options.See
assets/doc-template.gowhen writing doc comments for a new package or exported type and need a complete reference of all documentation conventions.
Normative: All top-level exported names must have doc comments.
// A Request represents a request to run a command.
type Request struct { ...
// Encode writes the JSON encoding of req to w.
func Encode(w io.Writer, req *Request) { ...
Unexported types/functions with unobvious behavior should also have doc comments.
Validation: After adding doc comments, run
bash scripts/check-docs.shto verify no exported symbols are missing documentation. Fix any gaps before proceeding.
Normative: Documentation comments must be complete sentences.
Advisory: Aim for ~80 columns, but no hard limit.
Break based on punctuation. Don't split long URLs.
Group fields with section comments. Mark optional fields with defaults:
type Options struct {
// General setup:
Name string
Group *FooGroup
// Customization:
LargeGroupThreshold int // optional; default: 10
}
Normative: Every package must have exactly one package comment.
// Package math provides basic constants and mathematical functions.
package math
main packages, use the binary name: // The seed_generator command ...doc.go fileRead references/EXAMPLES.md when writing package-level docs, main package comments, doc.go files, or runnable examples.
Advisory: Document non-obvious behavior, not obvious behavior.
| Topic | Document when... | Skip when... |
|---|---|---|
| Parameters | Non-obvious behavior, edge cases | Restates the type signature |
| Contexts | Behavior differs from standard cancellation | Standard ctx.Err() return |
| Concurrency | Ambiguous thread safety (e.g., read that mutates) | Read-only is safe, mutation is unsafe |
| Cleanup | Always document resource release | — |
| Errors | Sentinel values, error types (use *PathError) | — |
| Named results | Multiple params of same type, action-oriented names | Type alone is clear enough |
Key principles:
ctx.Err() is implied — don't restate itCall Stop to release resources)*PathError) for correct errors.Is/errors.AsRead references/CONVENTIONS.md when documenting parameter behavior, context cancellation, concurrency safety, cleanup requirements, error returns, or named result parameters in function doc comments.
Advisory: Provide runnable examples in test files (
*_test.go).
func ExampleConfig_WriteTo() {
cfg := &Config{Name: "example"}
cfg.WriteTo(os.Stdout)
// Output:
// {"name": "example"}
}
Examples appear in Godoc attached to the documented element.
Read references/EXAMPLES.md when writing runnable Example functions, choosing example naming conventions (Example vs ExampleType_Method), or adding package-level doc.go files.
Read references/FORMATTING.md when formatting godoc headings, links, lists, or code blocks, using signal boosting for deprecation notices, or previewing doc output locally.
| Topic | Key Rule |
|---|---|
| Doc comments | Start with name, use full sentences |
| Line length | ~80 chars, prioritize readability |
| Package comments | One per package, above package clause |
| Parameters | Document non-obvious behavior only |
| Contexts | Document exceptions to implied behavior |
| Concurrency | Document ambiguous thread safety |
| Cleanup | Always document resource release |
| Errors | Document sentinels and types (note pointer) |
| Examples | Use runnable examples in test files |
| Formatting | Blank lines for paragraphs, indent for code |
Example test functions that appear in godoc