{"id":"6baf6f3c-0ffe-4843-8f01-f3e5a5260e10","shortId":"L3Arfz","kind":"skill","title":"temporal-golang-pro","tagline":"Use when building durable distributed systems with Temporal Go SDK. Covers deterministic workflow rules, mTLS worker configs, and advanced patterns.","description":"# Temporal Go SDK (temporal-golang-pro)\n\n## Overview\n\nExpert-level guide for building resilient, scalable, and deterministic distributed systems using the Temporal Go SDK. This skill transforms vague orchestration requirements into production-grade Go implementations, focusing on durable execution, strict determinism, and enterprise-scale worker configuration.\n\n## When to Use This Skill\n\n- **Designing Distributed Systems**: When building microservices that require durable state and reliable orchestration.\n- **Implementing Complex Workflows**: Using the Go SDK to handle long-running processes (days/months) or complex Saga patterns.\n- **Optimizing Performance**: When workers need fine-tuned concurrency, mTLS security, or custom interceptors.\n- **Ensuring Reliability**: Implementing idempotent activities, graceful error handling, and sophisticated retry policies.\n- **Maintenance & Evolution**: Versioning running workflows or performing zero-downtime worker updates.\n\n## Do not use this skill when\n\n- Using Temporal with other SDKs (Python, Java, TypeScript) - refer to their specific `-pro` skills.\n- The task is a simple request/response without durability or coordination needs.\n- High-level design without implementation (use `workflow-orchestration-patterns`).\n\n## Step-by-Step Guide\n\n1.  **Gather Context**: Proactively ask for:\n    - Target **Temporal Cluster** (Cloud vs. Self-hosted) and **Namespace**.\n    - **Task Queue** names and expected throughput.\n    - **Security requirements** (mTLS paths, authentication).\n    - **Failure modes** and desired retry/timeout policies.\n2.  **Verify Determinism**: Before suggesting workflow code, verify against these **5 Rules**:\n    - No native Go concurrency (goroutines).\n    - No native time (`time.Now`, `time.Sleep`).\n    - No non-deterministic map iteration (must sort keys).\n    - No direct external I/O or network calls.\n    - No non-deterministic random numbers.\n3.  **Implement Incrementally**: Start with shared Protobuf/Data classes, then Activities, then Workflows, and finally Workers.\n4.  **Leverage Resources**: If the implementation requires advanced patterns (Sagas, Interceptors, Replay Testing), explicitly refer to the implementation playbook and testing strategies.\n\n## Capabilities\n\n### Go SDK Implementation\n\n- **Worker Management**: Deep knowledge of `worker.Options`, including `MaxConcurrentActivityTaskPollers`, `WorkerStopTimeout`, and `StickyScheduleToStartTimeout`.\n- **Interceptors**: Implementing Client, Worker, and Workflow interceptors for cross-cutting concerns (logging, tracing, auth).\n- **Custom Data Converters**: Integrating Protobuf, encrypted payloads, or custom JSON marshaling.\n\n### Advanced Workflow Patterns\n\n- **Durable Concurrency**: Using `workflow.Go`, `workflow.Channel`, and `workflow.Selector` instead of native primitives.\n- **Versioning**: Implementing safe code evolution using `workflow.GetVersion` and `workflow.GetReplaySafeLogger`.\n- **Large-scale Processing**: Pattern for `ContinueAsNew` to manage history size limits (defaults: 50MB or 50K events).\n- **Child Workflows**: Managing lifecycle, cancellation, and parent-child signal propagation.\n\n### Testing & Observability\n\n- **Testsuite Mastery**: Using `WorkflowTestSuite` for unit and functional testing with deterministic time control.\n- **Mocking**: Sophisticated activity and child workflow mocking strategies.\n- **Replay Testing**: Validating code changes against production event histories.\n- **Metrics**: Configuring Prometheus/OpenTelemetry exporters for worker performance tracking.\n\n## Examples\n\n### Example 1: Versioned Workflow (Deterministic)\n\n```go\n// Note: imports omitted. Requires 'go.temporal.io/sdk/workflow', 'go.temporal.io/sdk/temporal', and 'time'.\nfunc SubscriptionWorkflow(ctx workflow.Context, userID string) error {\n    // 1. Versioning for logic evolution (v1 = DefaultVersion)\n    v := workflow.GetVersion(ctx, \"billing_logic\", workflow.DefaultVersion, 2)\n\n    for i := 0; i < 12; i++ {\n        ao := workflow.ActivityOptions{\n            StartToCloseTimeout: 5 * time.Minute,\n            RetryPolicy: &temporal.RetryPolicy{MaximumAttempts: 3},\n        }\n        ctx = workflow.WithActivityOptions(ctx, ao)\n\n        // 2. Activity Execution (Always handle errors)\n        err := workflow.ExecuteActivity(ctx, ChargePaymentActivity, userID).Get(ctx, nil)\n        if err != nil {\n            workflow.GetLogger(ctx).Error(\"Payment failed\", \"Error\", err)\n            return err\n        }\n\n        // 3. Durable Sleep (Time-skipping safe)\n        sleepDuration := 30 * 24 * time.Hour\n        if v >= 2 {\n            sleepDuration = 28 * 24 * time.Hour\n        }\n\n        if err := workflow.Sleep(ctx, sleepDuration); err != nil {\n            return err\n        }\n    }\n    return nil\n}\n```\n\n### Example 2: Full mTLS Worker Setup\n\n```go\nfunc RunSecureWorker() error {\n    // 1. Load Client Certificate and Key\n    cert, err := tls.LoadX509KeyPair(\"client.pem\", \"client.key\")\n    if err != nil {\n        return fmt.Errorf(\"failed to load client keys: %w\", err)\n    }\n\n    // 2. Load CA Certificate for Server verification (Proper mTLS)\n    caPem, err := os.ReadFile(\"ca.pem\")\n    if err != nil {\n        return fmt.Errorf(\"failed to read CA cert: %w\", err)\n    }\n    certPool := x509.NewCertPool()\n    if !certPool.AppendCertsFromPEM(caPem) {\n        return fmt.Errorf(\"failed to parse CA cert\")\n    }\n\n    // 3. Dial Cluster with full TLS config\n    c, err := client.Dial(client.Options{\n        HostPort:  \"temporal.example.com:7233\",\n        Namespace: \"production\",\n        ConnectionOptions: client.ConnectionOptions{\n            TLS: &tls.Config{\n                Certificates: []tls.Certificate{cert},\n                RootCAs:      certPool,\n            },\n        },\n    })\n    if err != nil {\n        return fmt.Errorf(\"failed to dial temporal: %w\", err)\n    }\n    defer c.Close()\n\n    w := worker.New(c, \"payment-queue\", worker.Options{})\n    w.RegisterWorkflow(SubscriptionWorkflow)\n\n    if err := w.Run(worker.InterruptCh()); err != nil {\n        return fmt.Errorf(\"worker run failed: %w\", err)\n    }\n    return nil\n}\n```\n\n### Example 3: Selector & Signal Integration\n\n```go\nfunc ApprovalWorkflow(ctx workflow.Context) (string, error) {\n    var approved bool\n    signalCh := workflow.GetSignalChannel(ctx, \"approval-signal\")\n\n    // Use Selector to wait for multiple async events\n    s := workflow.NewSelector(ctx)\n    s.AddReceive(signalCh, func(c workflow.ReceiveChannel, _ bool) {\n        c.Receive(ctx, &approved)\n    })\n\n    // Add 72-hour timeout timer\n    s.AddReceive(workflow.NewTimer(ctx, 72*time.Hour).GetChannel(), func(c workflow.ReceiveChannel, _ bool) {\n        approved = false\n    })\n\n    s.Select(ctx)\n\n    if !approved {\n        return \"rejected\", nil\n    }\n    return \"approved\", nil\n}\n```\n\n## Best Practices\n\n- ✅ **Do:** Always handle errors from `ExecuteActivity` and `client.Dial`.\n- ✅ **Do:** Use `workflow.Go` and `workflow.Channel` for concurrency.\n- ✅ **Do:** Sort map keys before iteration to maintain determinism.\n- ✅ **Do:** Use `activity.RecordHeartbeat` for activities lasting > 1 minute.\n- ✅ **Do:** Test logic compatibility using `replayer.ReplayWorkflowHistoryFromJSON`.\n- ❌ **Don't:** Swallow errors with `_` or `log.Fatal` in production workers.\n- ❌ **Don't:** Perform direct Network/Disk I/O inside a Workflow function.\n- ❌ **Don't:** Rely on native `time.Now()` or `rand.Int()`.\n- ❌ **Don't:** Apply this to simple cron jobs that don't require durability.\n\n## Troubleshooting\n\n- **Panic: Determinism Mismatch**: Usually caused by logic changes without `workflow.GetVersion` or non-deterministic code (e.g., native maps).\n- **Error: History Size Exceeded**: History limit reached (default 50K events). Ensure `ContinueAsNew` is implemented.\n- **Worker Hang**: Check `WorkerStopTimeout` and ensure all activities handle context cancellation.\n\n## Limitations\n\n- Does not cover Temporal Cloud UI navigation or TLS certificate provisioning workflows.\n- Does not cover Temporal Java, Python, or TypeScript SDKs; refer to their dedicated `-pro` skills.\n- Assumes Temporal Server v1.20+ and Go SDK v1.25+; older SDK versions may have different APIs.\n- Does not cover experimental Temporal features (e.g., Nexus, Multi-cluster Replication).\n- Does not address global namespace configuration or multi-region failover setup.\n- Does not cover Temporal Worker versioning via the `worker-versioning` feature flag (experimental).\n\n## Resources\n\n- [Implementation Playbook](resources/implementation-playbook.md) - Deep dive into Go SDK patterns.\n- [Testing Strategies](resources/testing-strategies.md) - Unit, Replay, and Integration testing for Go.\n- [Temporal Go SDK Reference](https://pkg.go.dev/go.temporal.io/sdk)\n- [Temporal Go Samples](https://github.com/temporalio/samples-go)\n\n## Related Skills\n\n- `grpc-golang` - Internal transport protocol and Protobuf design.\n- `golang-pro` - General Go performance tuning and advanced syntax.\n- `workflow-orchestration-patterns` - Language-agnostic orchestration strategy.","tags":["temporal","golang","pro","antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding"],"capabilities":["skill","source-sickn33","skill-temporal-golang-pro","topic-agent-skills","topic-agentic-skills","topic-ai-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workflows","topic-antigravity","topic-antigravity-skills","topic-claude-code","topic-claude-code-skills","topic-codex-cli","topic-codex-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/temporal-golang-pro","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sickn33/antigravity-awesome-skills","source_repo":"https://github.com/sickn33/antigravity-awesome-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 34460 github stars · SKILL.md body (9,054 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-04-22T06:51:59.753Z","embedding":null,"createdAt":"2026-04-18T21:46:03.598Z","updatedAt":"2026-04-22T06:51:59.753Z","lastSeenAt":"2026-04-22T06:51:59.753Z","tsv":"'/go.temporal.io/sdk)':986 '/sdk/temporal'',':457 '/sdk/workflow'',':454 '/temporalio/samples-go)':992 '0':483 '1':195,443,467,565,786 '12':485 '2':228,480,500,539,556,588 '24':535,542 '28':541 '3':272,495,526,625,687 '30':534 '4':287 '5':238,490 '50k':388,862 '50mb':386 '72':728,735 'activ':128,281,418,501,784,875 'activity.recordheartbeat':782 'add':727 'address':936 'advanc':23,294,350,1012 'agnost':1020 'alway':503,757 'ao':487,499 'api':921 'appli':824 'approv':699,705,726,742,747,752 'approval-sign':704 'approvalworkflow':693 'ask':199 'assum':907 'async':713 'auth':338 'authent':221 'best':754 'bill':477 'bool':700,723,741 'build':7,38,83 'c':632,664,721,739 'c.close':661 'c.receive':724 'ca':590,609,623 'ca.pem':600 'call':265 'cancel':394,878 'capabl':309 'capem':597,617 'caus':840 'cert':571,610,624,646 'certif':568,591,644,889 'certpool':613,648 'certpool.appendcertsfrompem':616 'chang':428,843 'chargepaymentact':509 'check':870 'child':390,398,420 'class':279 'client':326,567,584 'client.connectionoptions':641 'client.dial':634,763 'client.key':575 'client.options':635 'client.pem':574 'cloud':204,884 'cluster':203,627,932 'code':234,367,427,850 'compat':791 'complex':93,107 'concern':335 'concurr':118,243,354,770 'config':21,631 'configur':73,434,939 'connectionopt':640 'context':197,877 'continueasnew':379,865 'control':415 'convert':341 'coordin':177 'cover':15,882,894,924,948 'cron':828 'cross':333 'cross-cut':332 'ctx':462,476,496,498,508,512,518,547,694,703,717,725,734,745 'custom':122,339,347 'cut':334 'data':340 'days/months':105 'dedic':904 'deep':315,964 'default':385,861 'defaultvers':473 'defer':660 'design':79,182,1003 'desir':225 'determin':67,230,779,837 'determinist':16,42,253,269,413,446,849 'dial':626,656 'differ':920 'direct':260,807 'distribut':9,43,80 'dive':965 'downtim':145 'durabl':8,64,87,175,353,527,834 'e.g':851,928 'encrypt':344 'ensur':124,864,873 'enterpris':70 'enterprise-scal':69 'err':506,515,523,525,545,549,552,572,577,587,598,602,612,633,650,659,672,675,683 'error':130,466,505,519,522,564,697,759,797,854 'event':389,431,714,863 'evolut':137,368,471 'exampl':441,442,555,686 'exceed':857 'execut':65,502 'executeact':761 'expect':215 'experiment':925,959 'expert':34 'expert-level':33 'explicit':300 'export':436 'extern':261 'fail':521,581,606,620,654,681 'failov':944 'failur':222 'fals':743 'featur':927,957 'final':285 'fine':116 'fine-tun':115 'flag':958 'fmt.errorf':580,605,619,653,678 'focus':62 'full':557,629 'func':460,562,692,720,738 'function':410,813 'gather':196 'general':1007 'get':511 'getchannel':737 'github.com':991 'github.com/temporalio/samples-go)':990 'global':937 'go':13,26,48,60,97,242,310,447,561,691,912,967,979,981,988,1008 'go.temporal.io':453,456 'go.temporal.io/sdk/temporal'',':455 'go.temporal.io/sdk/workflow'',':452 'golang':3,30,997,1005 'golang-pro':1004 'goroutin':244 'grace':129 'grade':59 'grpc':996 'grpc-golang':995 'guid':36,194 'handl':100,131,504,758,876 'hang':869 'high':180 'high-level':179 'histori':382,432,855,858 'host':208 'hostport':636 'hour':729 'i/o':262,809 'idempot':127 'implement':61,92,126,184,273,292,304,312,325,365,867,961 'import':449 'includ':319 'increment':274 'insid':810 'instead':360 'integr':342,690,976 'interceptor':123,297,324,330 'intern':998 'iter':255,776 'java':160,896 'job':829 'json':348 'key':258,570,585,774 'knowledg':316 'languag':1019 'language-agnost':1018 'larg':374 'large-scal':373 'last':785 'level':35,181 'leverag':288 'lifecycl':393 'limit':384,859,879 'load':566,583,589 'log':336 'log.fatal':800 'logic':470,478,790,842 'long':102 'long-run':101 'maintain':778 'mainten':136 'manag':314,381,392 'map':254,773,853 'marshal':349 'masteri':404 'maxconcurrentactivitytaskpol':320 'maximumattempt':494 'may':918 'metric':433 'microservic':84 'minut':787 'mismatch':838 'mock':416,422 'mode':223 'mtls':19,119,219,558,596 'multi':931,942 'multi-clust':930 'multi-region':941 'multipl':712 'must':256 'name':213 'namespac':210,638,938 'nativ':241,246,362,818,852 'navig':886 'need':114,178 'network':264 'network/disk':808 'nexus':929 'nil':513,516,550,554,578,603,651,676,685,750,753 'non':252,268,848 'non-determinist':251,267,847 'note':448 'number':271 'observ':402 'older':915 'omit':450 'optim':110 'orchestr':54,91,188,1016,1021 'os.readfile':599 'overview':32 'panic':836 'parent':397 'parent-child':396 'pars':622 'path':220 'pattern':24,109,189,295,352,377,969,1017 'payload':345 'payment':520,666 'payment-queu':665 'perform':111,142,439,806,1009 'pkg.go.dev':985 'pkg.go.dev/go.temporal.io/sdk)':984 'playbook':305,962 'polici':135,227 'practic':755 'primit':363 'pro':4,31,166,905,1006 'proactiv':198 'process':104,376 'product':58,430,639,802 'production-grad':57 'prometheus/opentelemetry':435 'propag':400 'proper':595 'protobuf':343,1002 'protobuf/data':278 'protocol':1000 'provis':890 'python':159,897 'queue':212,667 'rand.int':821 'random':270 'reach':860 'read':608 'refer':162,301,901,983 'region':943 'reject':749 'relat':993 'reli':816 'reliabl':90,125 'replay':298,424,974 'replayer.replayworkflowhistoryfromjson':793 'replic':933 'request/response':173 'requir':55,86,218,293,451,833 'resili':39 'resourc':289,960 'resources/implementation-playbook.md':963 'resources/testing-strategies.md':972 'retri':134 'retry/timeout':226 'retrypolici':492 'return':524,551,553,579,604,618,652,677,684,748,751 'rootca':647 'rule':18,239 'run':103,139,680 'runsecurework':563 's.addreceive':718,732 's.select':744 'safe':366,532 'saga':108,296 'sampl':989 'scalabl':40 'scale':71,375 'sdk':14,27,49,98,311,913,916,968,982 'sdks':158,900 'secur':120,217 'selector':688,708 'self':207 'self-host':206 'server':593,909 'setup':560,945 'share':277 'signal':399,689,706 'signalch':701,719 'simpl':172,827 'size':383,856 'skill':51,78,152,167,906,994 'skill-temporal-golang-pro' 'skip':531 'sleep':528 'sleepdur':533,540,548 'sophist':133,417 'sort':257,772 'source-sickn33' 'specif':165 'start':275 'starttoclosetimeout':489 'state':88 'step':191,193 'step-by-step':190 'stickyscheduletostarttimeout':323 'strategi':308,423,971,1022 'strict':66 'string':465,696 'subscriptionworkflow':461,670 'suggest':232 'swallow':796 'syntax':1013 'system':10,44,81 'target':201 'task':169,211 'tempor':2,12,25,29,47,155,202,657,883,895,908,926,949,980,987 'temporal-golang-pro':1,28 'temporal.example.com:7233':637 'temporal.retrypolicy':493 'test':299,307,401,411,425,789,970,977 'testsuit':403 'throughput':216 'time':247,414,459,530 'time-skip':529 'time.hour':536,543,736 'time.minute':491 'time.now':248,819 'time.sleep':249 'timeout':730 'timer':731 'tls':630,642,888 'tls.certificate':645 'tls.config':643 'tls.loadx509keypair':573 'topic-agent-skills' 'topic-agentic-skills' 'topic-ai-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workflows' 'topic-antigravity' 'topic-antigravity-skills' 'topic-claude-code' 'topic-claude-code-skills' 'topic-codex-cli' 'topic-codex-skills' 'trace':337 'track':440 'transform':52 'transport':999 'troubleshoot':835 'tune':117,1010 'typescript':161,899 'ui':885 'unit':408,973 'updat':147 'use':5,45,76,95,150,154,185,355,369,405,707,765,781,792 'userid':464,510 'usual':839 'v':474,538 'v1':472 'v1.20':910 'v1.25':914 'vagu':53 'valid':426 'var':698 'verif':594 'verifi':229,235 'version':138,364,444,468,917,951,956 'via':952 'vs':205 'w':586,611,658,662,682 'w.registerworkflow':669 'w.run':673 'wait':710 'without':174,183,844 'worker':20,72,113,146,286,313,327,438,559,679,803,868,950,955 'worker-vers':954 'worker.interruptch':674 'worker.new':663 'worker.options':318,668 'workerstoptimeout':321,871 'workflow':17,94,140,187,233,283,329,351,391,421,445,812,891,1015 'workflow-orchestration-pattern':186,1014 'workflow.activityoptions':488 'workflow.channel':357,768 'workflow.context':463,695 'workflow.defaultversion':479 'workflow.executeactivity':507 'workflow.getlogger':517 'workflow.getreplaysafelogger':372 'workflow.getsignalchannel':702 'workflow.getversion':370,475,845 'workflow.go':356,766 'workflow.newselector':716 'workflow.newtimer':733 'workflow.receivechannel':722,740 'workflow.selector':359 'workflow.sleep':546 'workflow.withactivityoptions':497 'workflowtestsuit':406 'x509.newcertpool':614 'zero':144 'zero-downtim':143","prices":[{"id":"849107d5-bcb6-4f9b-b9ac-06fa97855f44","listingId":"6baf6f3c-0ffe-4843-8f01-f3e5a5260e10","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T21:46:03.598Z"}],"sources":[{"listingId":"6baf6f3c-0ffe-4843-8f01-f3e5a5260e10","source":"github","sourceId":"sickn33/antigravity-awesome-skills/temporal-golang-pro","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/temporal-golang-pro","isPrimary":false,"firstSeenAt":"2026-04-18T21:46:03.598Z","lastSeenAt":"2026-04-22T06:51:59.753Z"}],"details":{"listingId":"6baf6f3c-0ffe-4843-8f01-f3e5a5260e10","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"temporal-golang-pro","github":{"repo":"sickn33/antigravity-awesome-skills","stars":34460,"topics":["agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity","antigravity-skills","claude-code","claude-code-skills","codex-cli","codex-skills","cursor","cursor-skills","developer-tools","gemini-cli","gemini-skills","kiro","mcp","skill-library"],"license":"mit","html_url":"https://github.com/sickn33/antigravity-awesome-skills","pushed_at":"2026-04-22T06:40:00Z","description":"Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.","skill_md_sha":"aabe4c5db02290dcce7a556eb2aef62bd34cd4a9","skill_md_path":"skills/temporal-golang-pro/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/temporal-golang-pro"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"name":"temporal-golang-pro","description":"Use when building durable distributed systems with Temporal Go SDK. Covers deterministic workflow rules, mTLS worker configs, and advanced patterns."},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/temporal-golang-pro"},"updatedAt":"2026-04-22T06:51:59.753Z"}}