{"id":"88946350-89c3-453e-bc70-fe355cfd2b94","shortId":"BGR9vA","kind":"skill","title":"go-functions","tagline":"Use when organizing functions within a Go file, formatting function signatures, designing return values, or following Printf-style naming conventions. Also use when a user is adding or refactoring any Go function, even if they don't mention function design or signature formatting","description":"# Go Function Design\n\n> **When this skill does NOT apply**: For functional options constructors (`WithTimeout`, `WithLogger`), see [go-functional-options](../go-functional-options/SKILL.md). For error return conventions, see [go-error-handling](../go-error-handling/SKILL.md). For naming functions and methods, see [go-naming](../go-naming/SKILL.md).\n\n---\n\n## Function Grouping and Ordering\n\nOrganize functions in a file by these rules:\n\n1. Functions sorted in **rough call order**\n2. Functions **grouped by receiver**\n3. **Exported** functions appear first, after `struct`/`const`/`var` definitions\n4. `NewXxx`/`newXxx` constructors appear right after the type definition\n5. Plain utility functions appear toward the end of the file\n\n```go\ntype something struct{ ... }\n\nfunc newSomething() *something { return &something{} }\n\nfunc (s *something) Cost() int { return calcCost(s.weights) }\n\nfunc (s *something) Stop() { ... }\n\nfunc calcCost(n []int) int { ... }\n```\n\n---\n\n## Function Signatures\n\n> Read [references/SIGNATURES.md](references/SIGNATURES.md) when formatting multi-line signatures, wrapping return values, shortening call sites, or replacing naked bool parameters with custom types.\n\nKeep the signature on a single line when possible. When it must wrap, put **all\narguments on their own lines** with a trailing comma:\n\n```go\nfunc (r *SomeType) SomeLongFunctionName(\n    foo1, foo2, foo3 string,\n    foo4, foo5, foo6 int,\n) {\n    foo7 := bar(foo1)\n}\n```\n\nAdd `/* name */` comments for ambiguous arguments, or better yet, replace naked\n`bool` parameters with custom types.\n\n---\n\n## Pointers to Interfaces\n\nYou almost never need a pointer to an interface. Pass interfaces as values — the\nunderlying data can still be a pointer.\n\n```go\n// Bad: pointer to interface\nfunc process(r *io.Reader) { ... }\n\n// Good: pass the interface value\nfunc process(r io.Reader) { ... }\n```\n\n---\n\n## Printf and Stringer\n\n> Read [references/PRINTF-STRINGER.md](references/PRINTF-STRINGER.md) when using Printf verbs beyond %v/%s/%d, implementing fmt.Stringer or fmt.GoStringer, writing custom Format() methods, or debugging infinite recursion in String() methods.\n\n### Printf-style Function Names\n\nFunctions that accept a format string should end in `f` for `go vet` support.\nDeclare format strings as `const` when used outside `Printf` calls.\n\nPrefer `%q` over `%s` with manual quoting when formatting strings for logging\nor error messages — it safely escapes special characters and wraps in quotes:\n\n```go\nreturn fmt.Errorf(\"unknown key %q\", key) // produces: unknown key \"foo\\nbar\"\n```\n\nSee **go-functional-options** when designing a constructor with 3+ optional\nparameters.\n\n---\n\n## Quick Reference\n\n| Topic | Rule |\n|-------|------|\n| File ordering | Type -> constructor -> exported -> unexported -> utils |\n| Signature wrapping | All args on own lines with trailing comma |\n| Naked parameters | Add `/* name */` comments or use custom types |\n| Pointers to interfaces | Almost never needed; pass interfaces by value |\n| Printf function names | End with `f` for `go vet` support |\n\n---\n\n## Related Skills\n\n- **Error returns**: See [go-error-handling](../go-error-handling/SKILL.md) when designing error return patterns or wrapping errors in multi-return functions\n- **Naming conventions**: See [go-naming](../go-naming/SKILL.md) when naming functions, methods, or choosing getter/setter patterns\n- **Functional options**: See [go-functional-options](../go-functional-options/SKILL.md) when designing a constructor with 3+ optional parameters\n- **Formatting principles**: See [go-style-core](../go-style-core/SKILL.md) when deciding line length, naked returns, or signature formatting","tags":["functions","golang","skills","cxuu","agent-skills","ai-agent","ai-assistant","claude","claude-code","codex","cursor","llm"],"capabilities":["skill","source-cxuu","skill-go-functions","topic-agent-skills","topic-ai-agent","topic-ai-assistant","topic-claude","topic-claude-code","topic-codex","topic-cursor","topic-golang","topic-llm"],"categories":["golang-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/cxuu/golang-skills/go-functions","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add cxuu/golang-skills","source_repo":"https://github.com/cxuu/golang-skills","install_from":"skills.sh"}},"qualityScore":"0.491","qualityRationale":"deterministic score 0.49 from registry signals: · indexed on github topic:agent-skills · 82 github stars · SKILL.md body (3,677 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T12:55:18.367Z","embedding":null,"createdAt":"2026-04-18T22:13:15.130Z","updatedAt":"2026-05-02T12:55:18.367Z","lastSeenAt":"2026-05-02T12:55:18.367Z","tsv":"'/go-error-handling/skill.md':78,459 '/go-functional-options/skill.md':68,495 '/go-naming/skill.md':88,479 '/go-style-core/skill.md':511 '1':101 '2':108 '3':113,397,501 '4':123 '5':133 'accept':329 'ad':31 'add':235,423 'almost':255,433 'also':25 'ambigu':239 'appear':116,127,137 'appli':56 'arg':414 'argument':210,240 'bad':276 'bar':233 'better':242 'beyond':303 'bool':190,246 'calccost':159,166 'call':106,185,350 'charact':370 'choos':485 'comma':218,420 'comment':237,425 'const':120,345 'constructor':60,126,395,407,499 'convent':24,72,474 'core':510 'cost':156 'custom':193,249,312,428 'd':306 'data':269 'debug':316 'decid':513 'declar':341 'definit':122,132 'design':15,44,50,393,461,497 'end':140,334,443 'error':70,76,364,452,457,462,467 'escap':368 'even':37 'export':114,408 'f':336,445 'file':11,97,143,404 'first':117 'fmt.errorf':377 'fmt.gostringer':310 'fmt.stringer':308 'follow':19 'foo':385 'foo1':224,234 'foo2':225 'foo3':226 'foo4':228 'foo5':229 'foo6':230 'foo7':232 'format':12,47,176,313,331,342,359,504,520 'func':148,153,161,165,220,280,289 'function':3,7,13,36,43,49,58,66,81,89,94,102,109,115,136,170,325,327,390,441,472,482,488,493 'getter/setter':486 'go':2,10,35,48,65,75,86,144,219,275,338,375,389,447,456,477,492,508 'go-error-handl':74,455 'go-funct':1 'go-functional-opt':64,388,491 'go-nam':85,476 'go-style-cor':507 'good':284 'group':90,110 'handl':77,458 'implement':307 'infinit':317 'int':157,168,169,231 'interfac':253,262,264,279,287,432,437 'io.reader':283,292 'keep':195 'key':379,381,384 'length':515 'line':179,201,214,417,514 'log':362 'manual':356 'mention':42 'messag':365 'method':83,314,321,483 'multi':178,470 'multi-lin':177 'multi-return':469 'must':206 'n':167 'nake':189,245,421,516 'name':23,80,87,236,326,424,442,473,478,481 'nbar':386 'need':257,435 'never':256,434 'newsometh':149 'newxxx':124,125 'option':59,67,391,398,489,494,502 'order':92,107,405 'organ':6,93 'outsid':348 'paramet':191,247,399,422,503 'pass':263,285,436 'pattern':464,487 'plain':134 'pointer':251,259,274,277,430 'possibl':203 'prefer':351 'principl':505 'printf':21,293,301,323,349,440 'printf-styl':20,322 'process':281,290 'produc':382 'put':208 'q':352,380 'quick':400 'quot':357,374 'r':221,282,291 'read':172,296 'receiv':112 'recurs':318 'refactor':33 'refer':401 'references/printf-stringer.md':297,298 'references/signatures.md':173,174 'relat':450 'replac':188,244 'return':16,71,151,158,182,376,453,463,471,517 'right':128 'rough':105 'rule':100,403 's.weights':160 'safe':367 'see':63,73,84,387,454,475,490,506 'shorten':184 'signatur':14,46,171,180,197,411,519 'singl':200 'site':186 'skill':53,451 'skill-go-functions' 'somelongfunctionnam':223 'someth':146,150,152,155,163 'sometyp':222 'sort':103 'source-cxuu' 'special':369 'still':271 'stop':164 'string':227,320,332,343,360 'stringer':295 'struct':119,147 'style':22,324,509 'support':340,449 'topic':402 'topic-agent-skills' 'topic-ai-agent' 'topic-ai-assistant' 'topic-claude' 'topic-claude-code' 'topic-codex' 'topic-cursor' 'topic-golang' 'topic-llm' 'toward':138 'trail':217,419 'type':131,145,194,250,406,429 'under':268 'unexport':409 'unknown':378,383 'use':4,26,300,347,427 'user':29 'util':135,410 'v':304 'valu':17,183,266,288,439 'var':121 'verb':302 'vet':339,448 'within':8 'withlogg':62 'withtimeout':61 'wrap':181,207,372,412,466 'write':311 'yet':243","prices":[{"id":"44e43056-16df-47f2-ae76-61ae4455ef19","listingId":"88946350-89c3-453e-bc70-fe355cfd2b94","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"cxuu","category":"golang-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:13:15.130Z"}],"sources":[{"listingId":"88946350-89c3-453e-bc70-fe355cfd2b94","source":"github","sourceId":"cxuu/golang-skills/go-functions","sourceUrl":"https://github.com/cxuu/golang-skills/tree/main/skills/go-functions","isPrimary":false,"firstSeenAt":"2026-04-18T22:13:15.130Z","lastSeenAt":"2026-05-02T12:55:18.367Z"}],"details":{"listingId":"88946350-89c3-453e-bc70-fe355cfd2b94","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"cxuu","slug":"go-functions","github":{"repo":"cxuu/golang-skills","stars":82,"topics":["agent-skills","ai-agent","ai-assistant","claude","claude-code","codex","cursor","go","golang","llm"],"license":"apache-2.0","html_url":"https://github.com/cxuu/golang-skills","pushed_at":"2026-03-15T19:32:10Z","description":"AI Agent Skills for idiomatic, production-ready Go code, distilled from Google, Uber, Community","skill_md_sha":"609add4edfb7d3a5b6ce4bc7ba69f5ceca205a9b","skill_md_path":"skills/go-functions/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/cxuu/golang-skills/tree/main/skills/go-functions"},"layout":"multi","source":"github","category":"golang-skills","frontmatter":{"name":"go-functions","license":"Apache-2.0","description":"Use when organizing functions within a Go file, formatting function signatures, designing return values, or following Printf-style naming conventions. Also use when a user is adding or refactoring any Go function, even if they don't mention function design or signature formatting. Does not cover functional options constructors (see go-functional-options)."},"skills_sh_url":"https://skills.sh/cxuu/golang-skills/go-functions"},"updatedAt":"2026-05-02T12:55:18.367Z"}}