/skill-temporal-developer

name: temporal-developer
description: Develop, debug, and manage Temporal applications across Python, TypeScript, Go, Java, .NET, Ruby, and Rust. Use when the user is building workflows, activities, workers, or background job queues with a Temporal SDK, debugging issues like non-determinism errors, stuck workflows, or activity retries, using Temporal CLI, Temporal Server, or Temporal Cloud, running Temporal with Docker Compose, or working with durable execution concepts like signals, queries, heartbeats, versioning, continue-as-new, child workflows, or saga patterns. Also use when the user mentions "run a Temporal workflow from the CLI", "start a dev server", "run temporal server start-dev", "temporal workflow start", "temporal workflow execute", "temporal workflow signal", "temporal workflow query", "temporal workflow update".

Skill: temporal-developer

Overview

Temporal is a durable execution platform that makes workflows survive failures automatically. This skill provides guidance for building Temporal applications in Python, TypeScript, Go, Java, .NET, Ruby, and Rust.

Out of Scope

• **Operational CLI commands** such as batch operations, health queries, Cloud administration, `tcld`, and scripting → use the [temporal-ops skill](https://github.com/temporalio/skill-temporal-ops).
• **Serverless Worker deployment and troubleshooting** → use the [temporal-serverless skill](https://github.com/temporalio/skill-temporal-serverless).
• **First-time Temporal Cloud setup** including a Namespace, API key, sample app, and first Workflow → use the [temporal-cloud-setup skill](https://github.com/temporalio/skill-temporal-cloud-setup).

If a task shifts into one of these areas, follow the relevant skill. Local development and developer-facing Workflow CLI commands remain covered here.

Core Architecture

The **Temporal Cluster** is the central orchestration backend. It maintains three key subsystems: the **Event History** (a durable log of all workflow state), **Task Queues** (which route work to the right workers), and a **Visibility** store (for searching and listing workflows). There are three ways to run a Cluster:

• **Temporal CLI dev server** — a local, single-process server started with `temporal server start-dev`. Suitable for development and testing only, not production.
• **Self-hosted** — you deploy and manage the Temporal server and its dependencies (e.g., database) in your own infrastructure for production use.
• **Temporal Cloud** — a fully managed production service operated by Temporal. No cluster infrastructure to manage.

**Workers** are long-running processes that you run and manage. They poll Task Queues for work and execute your code. You might run a single Worker process on one machine during development, or run many Worker processes across a large fleet of machines in production. Each Worker hosts two types of code:

• **Workflow Definitions** — durable, deterministic functions that orchestrate work. These must not have side effects.
• **Activity Implementations** — non-deterministic operations (API calls, file I/O, etc.) that can fail and be retried.

Workers communicate with the Cluster via a poll/complete loop: they poll a Task Queue for tasks, execute the corresponding Workflow or Activity code, and report results back.

History Replay: Why Determinism Matters

Temporal achieves durability through **history replay**:

1. **Initial Execution** - Worker runs workflow, generates Commands, stored as Events in history 2. **Recovery** - On restart/failure, Worker re-executes workflow from beginning 3. **Matching** - SDK compares generated Commands against stored Events 4. **Restoration** - Uses stored Activity results instead of re-executing

**If Commands don't match Events = Non-determinism Error = Workflow blocked**

See [Commands and Events](references/core/determinism.md#commands-and-events) for a table showing how Workflow actions are recorded in Event History.

Choose References for the Task

Identify the SDK language and the developer's task. Read the relevant core reference in the section below and its language-specific counterpart when available. Load additional references only as the task requires.

For a new project, a first implementation, or broad SDK guidance, read the appropriate SDK guide:

• Python -> [Python SDK guide](references/python/python.md)
• TypeScript -> [TypeScript SDK guide](references/typescript/typescript.md)
• Go -> [Go SDK guide](references/go/go.md)
• Java -> [Java SDK guide](references/java/java.md)
• .NET (C#) -> [.NET SDK guide](references/dotnet/dotnet.md)
• Ruby -> [Ruby SDK guide](references/ruby/ruby.md)
• Rust -> [Rust SDK guide](references/rust/rust.md) (in Public Preview)

For tasks that use Temporal CLI or start a local dev server, check whether `temporal` is installed before using it. If it is missing, follow the [Temporal CLI installation guide](references/core/install_cli.md).

Primary References

• **[Temporal determinism rules](references/core/determinism.md)** - Why determinism matters, replay mechanics, basic concepts of activities
• Language-specific info at `references/{your_language}/determinism.md`
• **Temporal workflow determinism protection** - SDK safeguards, analyzers, runtime checks, and their limits
• Language-specific info at `references/{your_language}/determinism-protection.md`
• **[Temporal workflow patterns](references/core/patterns.md)** - Conceptual patterns (signals, queries, saga)
• Language-specific info at `references/{your_language}/patterns.md`
• **[Temporal common pitfalls](references/core/gotchas.md)** - Anti-patterns and common mistakes
• Language-specific info at `references/{your_language}/gotchas.md`
• **[Temporal versioning guide](references/core/versioning.md)** - Versioning strategies and concepts - how to safely change workflow code while workflows are running
• Language-specific info at `references/{your_language}/versioning.md`
• **[Temporal standalon