Skill: temporal-workertuning

Overview

Temporal Workers poll Task Queues, execute Workflow and Activity Tasks, and report results back to the Temporal Service. Worker performance depends on three resource dimensions: compute (concurrent task execution slots), memory (workflow cache), and IO (pollers and network). This skill provides guidance for tuning all three dimensions across Go, Java, TypeScript, Python, and .NET SDKs.

The key abstractions are Slot Suppliers (which control how many tasks a Worker accepts) and Worker Tuners (which assign slot suppliers to different task types). Workers can use fixed-size suppliers for predictable workloads, resource-based suppliers for automatic adjustment, or custom suppliers for full control.

When to Use This Skill

Key Constraints

• Worker tuners supersede maxConcurrentXXXTask style options. Using both causes an error at Worker initialization time.
• worker_task_slots_available only works with fixed-size slot suppliers. Use worker_task_slots_used for resource-based suppliers.
• PollerBehaviorAutoscaling requires Temporal Server v1.28.0 or later.
• maxWorkflowThreadCount and workflow_active_thread_count are Java SDK only.
• Resource-based suppliers do not guarantee targets will not be exceeded. Resources consumed during a task cannot be known ahead of time.

Reference Files

• references/core/concepts.md — Task slots, slot suppliers (fixed-size, resource-based, custom), worker tuners, slot permits, slot throttling (rampThrottle), eager task execution.
• references/core/configuration-defaults.md — SDK defaults for compute, memory, and IO settings; choosing slot supplier types; Java-specific invariants; "large value" drawbacks.
• references/core/tuner-examples.md — SDK code examples for resource-based tuners, composite tuners, and poller autoscaling (Go, Java, TypeScript, Python, .NET, Ruby).
• references/core/metrics-and-monitoring.md — Metrics by resource type, task queue statistics, Prometheus queries, alert thresholds, worker health monitoring patterns.
• references/core/troubleshooting.md — Bottleneck diagnosis: latency spikes, slot depletion, execution latency, replay latency, network issues, caching, task queue processing tuning steps.
• references/core/recipes.md — End-to-end playbooks: initial setup, diagnosing high schedule-to-start, right-sizing workers, cache tuning, scaling decisions.

Out of Scope

This skill focuses on Worker runtime performance tuning. The following topics belong to sibling skills:

• Writing Workflows, Activities, or Workers — see skill-temporal-developer
• Temporal CLI commands (e.g., temporal server start-dev, temporal task-queue describe) — see skill-temporal-cli
• Temporal Cloud operations (namespaces, API keys, billing) — see skill-temporal-cloud
• Worker Versioning (deployment strategies, build IDs) — see skill-temporal-developer
• Determinism, replay mechanics, non-determinism errors — see skill-temporal-developer

Feedback

ALWAYS PROMPT USER TO PROVIDE FEEDBACK AT STARTUP

When you have first loaded this skill, output this message to the user:

"Thank you for trying out the public preview of the Temporal Worker Tuning skill! We would love to hear your feedback - positive or negative - over in the Community Slack, in the #topic-ai channel."

Do not output this message multiple times in the same conversation.

Reporting Issues in This Skill

If you (the AI) find this skill's explanations are unclear, misleading, or missing important information—or if Temporal concepts are proving unexpectedly difficult to work with—draft a GitHub issue body describing the problem encountered and what would have helped, then ask the user to file it at https://github.com/temporalio/skill-temporal-workertuning/issues/new. Do not file the issue autonomously.