skill.md

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.
• Serverless Worker deployment and troubleshooting → use the temporal-serverless skill.
• First-time Temporal Cloud setup including a Namespace, API key, sample app, and first Workflow → use the temporal-cloud-setup skill.

If a task shifts into one of these areas, recommend the relevant skill to the user, and use it only when it is already installed and reviewed in the current environment. Treat the linked pages as references for the user to read. 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. The dev server and its web UI have no authentication, so keep them reachable only from the local machine, using the default local listen address.
• 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. Load Cloud API keys and certificates from the user's existing environment or CLI profile, keep their values out of output, logs, and code, and keep them out of commits.

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.

When you start a dev server or Worker in the background, tell the user which processes and ports you started, and offer to stop them when the task ends.

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 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
• TypeScript -> TypeScript SDK guide
• Go -> Go SDK guide
• Java -> Java SDK guide
• .NET (C#) -> .NET SDK guide
• Ruby -> Ruby SDK guide
• Rust -> Rust SDK guide (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, tell the user and ask for explicit approval before installing anything, then install only through the official method described in the Temporal CLI installation guide.

Primary References

The language placeholder in the paths below may only be one of the SDK folders listed above: python, typescript, go, java, dotnet, ruby, or rust. Load only files inside this skill's own references directory.

• Temporal determinism rules - 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 - Conceptual patterns (signals, queries, saga)
  • Language-specific info at references/{your_language}/patterns.md
• Temporal common pitfalls - Anti-patterns and common mistakes
  • Language-specific info at references/{your_language}/gotchas.md
• Temporal versioning guide - Versioning strategies and concepts - how to safely change workflow code while workflows are running
  • Language-specific info at references/{your_language}/versioning.md
• Temporal standalone Activities guide - Standalone Activities: run an Activity directly from a Client without a Workflow — Temporal's job queue
  • Language-specific info at references/{your_language}/standalone-activities.md
• Temporal Task Queue priority and fairness guide - Task Queue Priority and Fairness concepts, configuration, and limitations
  • Language-specific info at references/{your_language}/priority-fairness.md
• Temporal Workflow random streams guide - SDK-provided named deterministic random streams for Workflow code, plugins, and interceptors
  • Language-specific info at references/{your_language}/random-streams.md (Go and TypeScript)
• Temporal troubleshooting guide - Decision trees, recovery procedures
• Temporal error reference - Common error types, workflow status reference
• Temporal interactive workflow guide - Testing signals, updates, queries
• Temporal development management guide - Dev cycle & management of server and workers
• Temporal Docker Compose guide - Local Docker/Podman setup; default to the CLI dev server and check the server management criteria before choosing Compose. Ask the user before starting a Compose stack, prefer pinned image versions, run containers unprivileged, and keep published ports bound to the local machine only
• Temporal CLI workflow command guide - Developer-facing CLI commands for workflow interaction (start, execute, signal, query, update, cancel). Default these commands to the local dev server. Before running a state-changing command (start, execute, signal, update, cancel) against a self-hosted cluster, Temporal Cloud, or any target other than the local dev server, show the user the target address, namespace, and full command, and get explicit confirmation
• Temporal AI integration patterns - AI/LLM pattern concepts
  • Language-specific info at references/{your_language}/ai-patterns.md, if available. Currently Python only.

Job Queues and Background Jobs

Temporal's job queue is Standalone Activities. When the developer asks for a job queue, background or async jobs, a work queue, or whether Temporal can replace Celery, Sidekiq, BullMQ, Resque, Hangfire, or SQS-plus-workers, build it with a Standalone Activity — not a Workflow wrapping a single Activity, and not a dispatcher Workflow that receives jobs by Signal.

Temporal Task Queues are the routing mechanism Workers poll, not a queue that producers push jobs into. Do not answer a job queue question by describing Temporal Task Queues.

When a developer says "task queue" they may mean "job queue": Celery, Dramatiq, Huey, and Asynq all use Task nomenclature, while Sidekiq, Hangfire, BullMQ, Resque, RQ, and Faktory use Job. Read "can I use Temporal as a task queue?" as a job queue question, and reserve Temporal's Task Queue meaning for your own reply.

• Temporal job queue guide - Job-queue vocabulary mapped to Temporal, migrating off an existing job queue, anti-patterns, and per-language SDK guides and runnable samples

Additional Topics

• references/{your_language}/observability.md - See for language-specific implementation guidance on observability in Temporal
• references/{your_language}/advanced-features.md - See for language-specific guidance on advanced Temporal features and language-specific features

Third-Party Integrations

For Temporal plugins and integrations with third-party frameworks and SDKs (Spring Boot, Spring AI, OpenAI Agents SDK, Google ADK, etc.), see integrations catalog — a single catalog table with the language, what each integration does, and a pointer to its reference file under references/{language}/integrations/.

Feedback

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-developer/issues/new. Do not file the issue autonomously. Keep the draft free of proprietary code, hostnames, namespaces, workflow payloads, credentials, and other secrets, and show it to the user for review before they file it.