evals/evals.json
{
"skill_name": "golang-documentation",
"evals": [
{
"id": 1,
"name": "readme-section-order",
"prompt": "Write a README.md for a Go library called `github.com/acme/taskflow` that provides a DAG-based task execution engine. It supports parallel execution, dependency resolution, cycle detection, and retry policies. Include installation instructions, a usage example, license info, and any other sections you think are appropriate for a Go open-source library.",
"trap": "Model will produce a reasonable README but likely not follow the exact section order: Title > Badges > Summary > Demo > Getting Started > Features > Contributing > License",
"assertions": [
{
"id": "1.1",
"text": "Badges section appears immediately after the title heading, before any prose"
},
{
"id": "1.2",
"text": "A short summary (1-2 sentences) appears after badges, before any code block or Getting Started section"
},
{
"id": "1.3",
"text": "A demo/example code snippet appears before the Getting Started/Installation section"
},
{
"id": "1.4",
"text": "Getting Started section with `go get` appears after the demo and before Features"
},
{
"id": "1.5",
"text": "Features section is the longest section, appearing after Getting Started"
}
]
},
{
"id": 2,
"name": "scrambled-readme-reorder",
"prompt": "I wrote a README for my Go library `github.com/acme/ratelimit` but my team says the sections are in the wrong order. Can you reorganize it following Go open-source best practices? Keep the content, just fix the order:\n\n```markdown\n# ratelimit\n\n## Getting Started\n```bash\ngo get github.com/acme/ratelimit\n```\n\n## Features\n- Token bucket algorithm\n- Redis backend support\n- Per-key rate limiting\n- Middleware for net/http\n\nA high-performance, distributed rate limiter for Go applications.\n\n## License\nMIT License - see LICENSE file.\n\n[](https://github.com/acme/ratelimit/actions)\n\n## Contributing\nSee CONTRIBUTING.md\n\n```go\nlimiter := ratelimit.New(ratelimit.WithRate(100, time.Second))\nif limiter.Allow(\"user-123\") {\n // process request\n}\n```\n```\n",
"trap": "The README has sections in wrong order: Getting Started > Features > Summary (unlabeled) > License > Badges (unlabeled) > Contributing > Demo (unlabeled). Without skill the model might rearrange reasonably but miss the exact prescribed order or miss that Summary/Badges/Demo need their own placement",
"assertions": [
{
"id": "2.1",
"text": "Badges appear immediately after the title, before the summary text"
},
{
"id": "2.2",
"text": "The summary sentence ('A high-performance...') appears after badges, before the demo code"
},
{
"id": "2.3",
"text": "The demo code snippet (limiter := ...) appears before the Getting Started section"
},
{
"id": "2.4",
"text": "Getting Started appears after demo and before Features"
},
{
"id": "2.5",
"text": "Contributing and License appear at the end, after Features"
}
]
},
{
"id": 3,
"name": "doc-comment-why-not-what",
"prompt": "Write a godoc comment for this Go function. Make it comprehensive:\n\n```go\nfunc Merge(dst, src map[string]interface{}, overwrite bool) map[string]interface{} {\n if dst == nil {\n dst = make(map[string]interface{})\n }\n for k, v := range src {\n if _, exists := dst[k]; !exists || overwrite {\n dst[k] = v\n }\n }\n return dst\n}\n```",
"trap": "Model might just restate: 'Merge merges two maps'. Skill teaches why/when/constraints, Parameters section, Returns section, error cases",
"assertions": [
{
"id": "3.1",
"text": "Comment starts with 'Merge' followed by a verb phrase (godoc convention)"
},
{
"id": "3.2",
"text": "Includes a Parameters section listing dst, src, and overwrite with descriptions"
},
{
"id": "3.3",
"text": "Explains the overwrite behavior (when true vs false)"
},
{ "id": "3.4", "text": "Documents nil dst handling (creates new map)" },
{
"id": "3.5",
"text": "Includes an inline code Example section showing usage"
}
]
},
{
"id": 4,
"name": "small-package-no-doc-go",
"prompt": "I have a Go package with 2 files: `handler.go` and `middleware.go`. My teammate suggests I should create a `doc.go` file for the package-level documentation comment. Is that the right approach? Where should I put the package comment?",
"trap": "Model without skill might agree to create doc.go (it's a common pattern). Skill teaches: doc.go is for packages with 3+ files; for small packages, put the comment at the top of the main .go file",
"assertions": [
{
"id": "4.1",
"text": "Advises AGAINST creating doc.go for a 2-file package"
},
{
"id": "4.2",
"text": "Recommends placing the package comment at the top of the main .go file (handler.go)"
},
{
"id": "4.3",
"text": "Mentions the 3+ files threshold for when doc.go becomes appropriate"
},
{
"id": "4.4",
"text": "Shows the `// Package ... ` format starting with the Package keyword"
},
{
"id": "4.5",
"text": "Explains that doc.go is for larger packages where no single file is the obvious home"
}
]
},
{
"id": 5,
"name": "example-test-naming",
"prompt": "Write Example test functions for this Go library function that converts temperatures. I need examples for: basic Celsius to Fahrenheit, Fahrenheit to Celsius, and Kelvin to Celsius conversions.\n\n```go\npackage tempconv\n\n// Convert converts a temperature from one unit to another.\nfunc Convert(value float64, from, to Unit) float64 { ... }\n```",
"trap": "Model might name multiple examples as ExampleConvert1/ExampleConvert2 or ExampleConvertCelsiusToFahrenheit (capitalized suffix). Skill teaches lowercase suffix convention.",
"assertions": [
{
"id": "5.1",
"text": "Uses external test package (package tempconv_test)"
},
{
"id": "5.2",
"text": "Multiple examples use lowercase suffix: ExampleConvert_celsiusToFahrenheit or similar lowercase pattern"
},
{
"id": "5.3",
"text": "Every example includes an // Output: comment for go test verification"
},
{
"id": "5.4",
"text": "Examples use fmt.Println to print results (not fmt.Printf)"
},
{
"id": "5.5",
"text": "Examples import the package and call tempconv.Convert (external test package pattern)"
}
]
},
{
"id": 6,
"name": "contributing-10min-rule",
"prompt": "Write a CONTRIBUTING.md for a Go project that requires: PostgreSQL 15, Redis 7, Elasticsearch 8, Go 1.22+, and protoc for gRPC code generation. The test suite takes about 3 minutes to run. Building requires running `protoc` first, then `go generate`, then `go build`.",
"trap": "Complex setup with 5 dependencies. Model might just list prerequisites. Skill teaches the 10-minute rule and suggests Makefile, docker-compose, devcontainer",
"assertions": [
{
"id": "6.1",
"text": "Includes a Makefile or mentions make targets (make build, make test, make lint)"
},
{
"id": "6.2",
"text": "Includes docker-compose.yml for running PostgreSQL, Redis, and Elasticsearch locally"
},
{
"id": "6.3",
"text": "Provides a Quick Start section showing clone-to-running-tests in a few commands"
},
{
"id": "6.4",
"text": "Mentions or provides devcontainer configuration for consistent environments"
},
{
"id": "6.5",
"text": "Separates unit tests (fast, no deps) from integration tests (needs services)"
}
]
},
{
"id": 7,
"name": "security-fix-miscategorized",
"prompt": "We use Keep a Changelog format. A junior developer wrote this CHANGELOG entry for our new release. Is it correct?\n\n```markdown\n## [2.3.0] - 2026-04-10\n\n### Added\n- New streaming API for large file transfers\n- Support for HTTP/3\n\n### Fixed\n- Null pointer dereference when config is missing\n- Deserialization flaw allowing arbitrary code execution via malformed input (GHSA-xxxx-yyyy-zzzz)\n- Off-by-one error in retry backoff calculation\n\n### Changed\n- Connection pool default size increased to 50\n```",
"trap": "The GHSA vulnerability is listed under Fixed. Per Keep a Changelog format, security fixes belong in a dedicated ### Security section. A model without skill knowledge treats all bug fixes as Fixed and has no reason to split them. The model must know that Keep a Changelog defines Security as its own top-level category.",
"assertions": [
{
"id": "7.1",
"text": "Identifies that the GHSA/deserialization fix belongs in a dedicated ### Security section, not ### Fixed"
},
{
"id": "7.2",
"text": "Recommends creating a ### Security subsection that is separate from ### Fixed"
},
{
"id": "7.3",
"text": "Keeps the null pointer and off-by-one fixes under ### Fixed — they are bugs, not vulnerabilities"
},
{
"id": "7.4",
"text": "Does not move non-security bugs into the Security section"
},
{
"id": "7.5",
"text": "Notes that the Security category exists as its own top-level changelog category, not a subcategory of Fixed"
}
]
},
{
"id": 8,
"name": "llms-txt",
"prompt": "I have a Go library `github.com/acme/querybuilder` that provides a type-safe SQL query builder. It has these main types: Builder, Query, Condition, JoinClause. Main functions: New(), Select(), Insert(), Update(), Delete(). Errors: ErrInvalidColumn, ErrMissingTable. I want to make my library more accessible to AI coding assistants. What should I do and can you create any needed files?",
"trap": "Model without skill won't know about llms.txt convention. Might suggest better README or doc comments only.",
"assertions": [
{
"id": "8.1",
"text": "Creates or recommends creating an llms.txt file at the repository root"
},
{
"id": "8.2",
"text": "llms.txt includes an Overview section explaining what the library does"
},
{
"id": "8.3",
"text": "llms.txt includes Key Concepts or API Reference listing the main types and functions"
},
{
"id": "8.4",
"text": "llms.txt includes Common Patterns section with code examples"
},
{
"id": "8.5",
"text": "Mentions registering for discoverability platforms (Context7, DeepWiki, or similar)"
}
]
},
{
"id": 9,
"name": "brief-doc-comment-trap",
"prompt": "Write a brief, one-line doc comment for this exported Go function. Keep it short — I don't want verbose documentation cluttering the code:\n\n```go\npackage retry\n\nfunc Do(ctx context.Context, maxAttempts int, delay time.Duration, backoff float64, fn func() error) error {\n var lastErr error\n for i := 0; i < maxAttempts; i++ {\n if err := fn(); err != nil {\n lastErr = err\n select {\n case <-ctx.Done():\n return ctx.Err()\n case <-time.After(delay):\n delay = time.Duration(float64(delay) * backoff)\n }\n continue\n }\n return nil\n }\n return lastErr\n}\n```",
"trap": "User explicitly asks for 'brief, one-line'. Without skill, model complies and writes a minimal one-liner. With skill, the model should STILL write a comprehensive comment because the skill says every exported function MUST have a doc comment with Parameters, Returns, and Example sections",
"assertions": [
{
"id": "9.1",
"text": "Comment starts with 'Do' followed by a verb phrase (godoc convention)"
},
{
"id": "9.2",
"text": "Includes a Parameters section or describes each parameter (ctx, maxAttempts, delay, backoff, fn)"
},
{
"id": "9.3",
"text": "Documents the exponential backoff behavior (delay multiplied by backoff factor)"
},
{
"id": "9.4",
"text": "Documents context cancellation behavior (returns ctx.Err())"
},
{
"id": "9.5",
"text": "Includes an inline Example section showing a realistic usage pattern"
}
]
},
{
"id": 10,
"name": "review-restating-comments",
"prompt": "Review these doc comments. My team says our documentation is solid. Do you see any issues?\n\n```go\npackage cache\n\n// Get gets a value from the cache by key.\n// Returns the value and true if found, zero value and false if not.\nfunc (c *Cache) Get(key string) (interface{}, bool) { ... }\n\n// Set sets a value in the cache for the given key.\nfunc (c *Cache) Set(key string, value interface{}) { ... }\n\n// Delete deletes a value from the cache by key.\nfunc (c *Cache) Delete(key string) { ... }\n\n// Size returns the number of items currently in the cache.\nfunc (c *Cache) Size() int { ... }\n\n// Clear clears all items from the cache.\nfunc (c *Cache) Clear() { ... }\n```",
"trap": "Team says docs are 'solid', creating social pressure to agree. All comments describe what the code does but not why/when/constraints — they omit thread safety, TTL/eviction behavior, and cache miss semantics. The skill requires comments to explain WHY and WHEN, not just WHAT.",
"assertions": [
{
"id": "10.1",
"text": "Identifies that the comments describe WHAT the code does but fail to explain WHY, WHEN, or any constraints"
},
{
"id": "10.2",
"text": "Points out that Get is missing thread-safety documentation (is it safe for concurrent use?)"
},
{
"id": "10.3",
"text": "Points out that Set is missing documentation on what happens if the key already exists and whether there is a TTL or capacity limit"
},
{
"id": "10.4",
"text": "Rewrites at least one comment to include constraints, edge cases, or concurrent-use guarantees"
},
{
"id": "10.5",
"text": "Does NOT simply agree that the docs are solid without identifying the missing context"
}
]
},
{
"id": 11,
"name": "skip-test-func-comments",
"prompt": "I'm adding doc comments to every function in my Go project to reach 100% documentation coverage. Please add appropriate doc comments to these test functions:\n\n```go\npackage auth_test\n\nfunc TestValidateToken(t *testing.T) { ... }\nfunc TestValidateToken_expired(t *testing.T) { ... }\nfunc TestValidateToken_invalidSignature(t *testing.T) { ... }\nfunc BenchmarkValidateToken(b *testing.B) { ... }\nfunc TestHashPassword(t *testing.T) { ... }\nfunc TestComparePassword(t *testing.T) { ... }\n```",
"trap": "User explicitly asks to add doc comments to test functions citing '100% documentation coverage'. Without skill, model complies and writes comments for each test. The skill's 'What to Document' table explicitly says 'Test functions: No' and the model should push back on this request.",
"assertions": [
{
"id": "11.1",
"text": "Advises against or actively discourages adding doc comments to test functions"
},
{
"id": "11.2",
"text": "Explains that test function names are designed to be self-descriptive — the name IS the documentation"
},
{
"id": "11.3",
"text": "Does NOT produce doc comments for any of the standard Test/Benchmark functions listed"
},
{
"id": "11.4",
"text": "Clarifies that '100% documentation coverage' tools do not count unexported or test functions — this goal does not apply here"
},
{
"id": "11.5",
"text": "May suggest that complex test setup helpers warrant comments, but not the standard TestXxx/BenchmarkXxx functions themselves"
}
]
},
{
"id": 12,
"name": "simple-crud-no-file-desc",
"prompt": "I have a Go file `user_handler.go` (120 lines) that contains standard CRUD HTTP handlers for a User resource: CreateUser, GetUser, UpdateUser, DeleteUser, and ListUsers. Each handler does basic JSON decode, calls a service, and returns a JSON response. Should I add a file-level description comment with an architecture diagram like I did for my scheduler file?",
"trap": "User references having added a file description to a complex scheduler file and wants to do the same for a simple CRUD handler. Without skill, model might agree or add unnecessary documentation. With skill, model should say NO — simple CRUD handlers don't warrant file-level descriptions per the 'When to Add File Descriptions' table",
"assertions": [
{
"id": "12.1",
"text": "Advises against adding a file-level description for this CRUD handler"
},
{
"id": "12.2",
"text": "Explains that simple CRUD handlers don't warrant the same treatment as complex algorithms"
},
{
"id": "12.3",
"text": "Distinguishes between when file descriptions ARE needed (algorithms, state machines, 200+ lines of complex logic) vs not needed (CRUD, data models)"
},
{
"id": "12.4",
"text": "Still recommends good doc comments on the individual exported handler functions"
},
{
"id": "12.5",
"text": "Does NOT produce an ASCII art diagram or elaborate file-level description"
}
]
},
{
"id": 13,
"name": "file-level-description",
"prompt": "I have a Go file `scheduler.go` that implements a priority-queue-based task scheduler using container/heap. It supports recurring tasks, one-shot tasks, task cancellation, and graceful shutdown with a drain timeout. A single dispatcher goroutine polls the heap. The file is 350 lines. Should I add any special documentation to this file, and if so, what?",
"trap": "Model might just say 'add function comments'. Skill teaches file-level description with ASCII art architecture diagram for complex files",
"assertions": [
{
"id": "13.1",
"text": "Recommends a file-level description comment (not just function comments)"
},
{
"id": "13.2",
"text": "Suggests including an ASCII art diagram showing the scheduler architecture/flow"
},
{
"id": "13.3",
"text": "Places the file description below imports (not above package declaration)"
},
{
"id": "13.4",
"text": "Description explains the algorithm/design (priority queue, dispatcher goroutine)"
},
{
"id": "13.5",
"text": "Notes the 200+ line threshold or 'complex algorithm' as reason for adding the description"
}
]
},
{
"id": 14,
"name": "grpc-api-docs",
"prompt": "I have a Go gRPC service for user management. The proto file currently has no comments at all. A teammate says I should use swaggo/swag since we already use it for our REST API. What's the right way to document a gRPC API?",
"trap": "Teammate explicitly suggests swaggo/swag for gRPC. The model must know that swaggo/swag generates OpenAPI from Go HTTP annotations — it has no concept of protobufs. Without skill knowledge, the model might go along with the suggestion or give a vague answer. With skill, the model knows proto files are the source of truth and buf is the right tool.",
"assertions": [
{
"id": "14.1",
"text": "Clearly states that swaggo/swag is NOT the right tool for gRPC — it generates OpenAPI for REST APIs, not protobuf documentation"
},
{
"id": "14.2",
"text": "States that proto files themselves serve as the API contract AND documentation — add comments there"
},
{
"id": "14.3",
"text": "Recommends adding comments directly to proto messages, services, and RPCs"
},
{
"id": "14.4",
"text": "Recommends buf for proto linting and breaking change detection"
},
{
"id": "14.5",
"text": "Mentions grpc-gateway as an option for projects needing both REST and gRPC from the same proto"
}
]
},
{
"id": 15,
"name": "app-disguised-as-library",
"prompt": "I'm building a Go project at `github.com/acme/datactl`. The project structure is:\n```\ncmd/\n datactl/\n main.go\ninternal/\n ingester/\n transformer/\n exporter/\npkg/\n config/\n client/\ngo.mod\n```\nThe `pkg/` directory exports a client SDK that other teams import. The `cmd/` directory builds the CLI binary. What documentation strategy should I use? Should I write ExampleXxx tests and Playground demos for the exported packages?",
"trap": "Project is BOTH a library (pkg/) AND an application (cmd/). Without skill, model might treat it as one or the other. With skill, model should detect both types and apply different documentation strategies: ExampleXxx for pkg/, CLI help + install methods for cmd/",
"assertions": [
{
"id": "15.1",
"text": "Identifies this as BOTH a library (pkg/) AND an application (cmd/) — not just one type"
},
{
"id": "15.2",
"text": "Recommends ExampleXxx test functions for the pkg/client and pkg/config packages (library part)"
},
{
"id": "15.3",
"text": "Recommends CLI --help text and multiple installation methods for the cmd/datactl binary (application part)"
},
{
"id": "15.4",
"text": "Recommends configuration documentation (env vars, config files, flags) for the CLI"
},
{
"id": "15.5",
"text": "Does NOT recommend Playground demos for internal/ packages (they are not importable by external users)"
}
]
},
{
"id": 16,
"name": "existing-contributing-improve",
"prompt": "Our Go project requires PostgreSQL and Redis. This is our current CONTRIBUTING.md. Improve it:\n\n```markdown\n# Contributing\n\n## Prerequisites\n- Go 1.22+\n- PostgreSQL 15\n- Redis 7\n\n## Setup\n1. Install Go from https://go.dev\n2. Install PostgreSQL from https://www.postgresql.org/download/\n3. Install Redis from https://redis.io/download/\n4. Create a database: `createdb myapp_test`\n5. Run `go build ./...`\n6. Run `go test ./...`\n\n## Pull Requests\nPlease open a PR against the main branch.\n```",
"trap": "The existing CONTRIBUTING requires manual installation of PostgreSQL and Redis — time-consuming and error-prone. Without skill, model might polish the text or add small improvements. With skill, model should apply the 10-minute rule: replace manual installs with docker-compose, add Makefile, suggest devcontainer",
"assertions": [
{
"id": "16.1",
"text": "Adds docker-compose.yml to replace manual PostgreSQL and Redis installation"
},
{
"id": "16.2",
"text": "Adds a Makefile with targets (make build, make test, make lint, or similar)"
},
{
"id": "16.3",
"text": "Reduces the setup steps to 3 or fewer commands (e.g., clone, docker-compose up, make test)"
},
{
"id": "16.4",
"text": "Mentions or suggests devcontainer for consistent environments"
},
{
"id": "16.5",
"text": "Separates unit tests (fast, no deps) from integration tests (needs PostgreSQL/Redis)"
}
]
},
{
"id": 17,
"name": "play-link-doc-comment",
"prompt": "I maintain a public Go library. Write a comprehensive doc comment for this function. I need it to show up well on pkg.go.dev — include everything users need to understand it at a glance:\n\n```go\npackage sliceutil\n\nfunc Filter[T any](s []T, predicate func(T) bool) []T {\n var result []T\n for _, v := range s {\n if predicate(v) {\n result = append(result, v)\n }\n }\n return result\n}\n```",
"trap": "Model may write a thorough doc comment but omit the Play: line entirely — it's a niche convention the skill specifically teaches. The Play: line with its exact format (// Play: https://...) is a skill-specific pattern not commonly known.",
"assertions": [
{
"id": "17.1",
"text": "Includes a `// Play:` line with a URL pointing to a Go Playground demo"
},
{
"id": "17.2",
"text": "The Play: line uses the exact format `// Play: https://go.dev/play/p/...` (not inline, not as a different label)"
},
{
"id": "17.3",
"text": "Comment starts with 'Filter' followed by a verb phrase"
},
{
"id": "17.4",
"text": "Includes an inline code Example section (tab-indented)"
},
{
"id": "17.5",
"text": "Documents that a new slice is returned (original is not modified)"
}
]
},
{
"id": 18,
"name": "architecture-decision-records",
"prompt": "Our Go project has made several important architectural decisions: using PostgreSQL over MongoDB, choosing event-driven architecture with NATS, and using JWT for authentication. How should we document these decisions so future team members understand the rationale?",
"trap": "Model might suggest a wiki page or a section in README. Skill teaches docs/architecture/ directory with numbered ADR files",
"assertions": [
{
"id": "18.1",
"text": "Recommends a docs/architecture/ directory (not wiki or README section)"
},
{
"id": "18.2",
"text": "Uses numbered file format (0001-xxx.md, 0002-xxx.md)"
},
{
"id": "18.3",
"text": "Each ADR has Context section explaining the need"
},
{
"id": "18.4",
"text": "Each ADR has Design/Decision section explaining what was chosen"
},
{
"id": "18.5",
"text": "Each ADR has Consequences section (positive and negative trade-offs)"
}
]
},
{
"id": 19,
"name": "example-method-naming",
"prompt": "Write Example test functions for this Go type and its methods. Cover: creating a new client, making a GET request, making a POST request with a body, and setting custom headers.\n\n```go\npackage httpclient\n\ntype Client struct { ... }\nfunc New(opts ...Option) *Client { ... }\nfunc (c *Client) Get(ctx context.Context, url string) (*Response, error) { ... }\nfunc (c *Client) Post(ctx context.Context, url string, body io.Reader) (*Response, error) { ... }\nfunc (c *Client) SetHeader(key, value string) { ... }\n```",
"trap": "The method example naming convention (ExampleClient_Get, ExampleClient_Post) is less well known than the function convention. Without the skill, the model may write ExampleGetRequest, ExamplePost, ExampleClient_GetRequest (mixing conventions), or use capitalized suffixes. The exact pattern is TypeName_MethodName.",
"assertions": [
{
"id": "19.1",
"text": "Uses ExampleNew or ExampleClient for the constructor example — NOT ExampleNewClient (which stutters) or ExampleNew_client"
},
{
"id": "19.2",
"text": "Uses ExampleClient_Get for the GET request example (TypeName_MethodName convention with capital method name)"
},
{
"id": "19.3",
"text": "Uses ExampleClient_Post for the POST request example (same TypeName_MethodName pattern)"
},
{
"id": "19.4",
"text": "Every example includes an // Output: comment"
},
{
"id": "19.5",
"text": "Uses external test package (package httpclient_test)"
}
]
},
{
"id": 20,
"name": "discoverability-registration",
"prompt": "I just published my Go library on GitHub (public repo, MIT license, tagged v1.0.0). I have a good README, doc comments, ExampleXxx tests, and a CHANGELOG. What else should I do to make sure developers and AI tools can find and use my library?",
"trap": "Model without skill knowledge of the specific platforms will give generic answers: 'share on social media', 'write a blog post', 'submit to HackerNews'. The skill teaches specific discoverability platforms: Context7, DeepWiki, OpenDeep, zRead — names the model won't know without the skill.",
"assertions": [
{
"id": "20.1",
"text": "Recommends registering with Context7 (context7.com) specifically for AI-accessible documentation"
},
{
"id": "20.2",
"text": "Recommends registering with DeepWiki (deepwiki.com) specifically"
},
{
"id": "20.3",
"text": "Recommends adding an llms.txt file at the repository root"
},
{
"id": "20.4",
"text": "Recommends adding Go Playground demos linked from doc comments with the // Play: format"
},
{
"id": "20.5",
"text": "Names at least 3 specific discoverability platforms (from: Context7, DeepWiki, OpenDeep, zRead) — not generic promotion advice"
}
]
},
{
"id": 21,
"name": "deprecated-marker-format",
"prompt": "I'm deprecating a function in my Go library. The old function is `ParseDuration` and the new replacement is `ParseDurationStrict`. Write the doc comment for the deprecated function. Also, I want to make sure automated tools and pkg.go.dev show it as deprecated correctly.",
"trap": "Model might use a freeform deprecation notice (e.g., 'This function is deprecated, use X instead') instead of the specific godoc Deprecated: marker format that tools recognize. The exact format with 'Deprecated:' on its own paragraph line is required for godoc rendering and tooling detection",
"assertions": [
{
"id": "21.1",
"text": "Uses the exact 'Deprecated:' marker (capital D, colon, space) on its own comment paragraph line — this is the format godoc and tools recognize"
},
{
"id": "21.2",
"text": "Includes the replacement function name (ParseDurationStrict) after the Deprecated: marker"
},
{
"id": "21.3",
"text": "Mentions a version or timeline for removal (e.g., 'will be removed in v3.0.0')"
}
]
}
]
}
SKILL.md
---
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](./references/library.md)
**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](./references/application.md)
**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:
```go
// 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](./references/code-comments.md)** — 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](./assets/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:
```markdown
[](https://go.dev/) [](./LICENSE) [](https://github.com/{owner}/{repo}/actions) [](https://codecov.io/gh/{owner}/{repo}) [](https://goreportcard.com/report/github.com/{owner}/{repo}) [](https://pkg.go.dev/github.com/{owner}/{repo})
```
For the full README guidance and application-specific sections, see [Project Docs](./references/project-docs.md#readme).
## 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](./references/project-docs.md#contributingmd).
**Changelog** — Track changes using [Keep a Changelog](https://keepachangelog.com/) format or GitHub Releases, copying the template from [templates/CHANGELOG.md](./assets/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](./references/project-docs.md#changelog).
## 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](https://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](./references/library.md) 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](./references/application.md) 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](./references/application.md#api-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](./assets/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:**
```bash
go get github.com/{owner}/{repo}
```
**Applications:**
```bash
# 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](./references/project-docs.md#delivery) for Dockerfile best practices and Homebrew tap setup.