Temporal Developer

OpenAIOfficialCreated by TemporalDistributed by OpenAI

Skill
Tool integration
Software development
MIT
Low risk

From the author

Develop, debug, and manage Temporal applications across Python, TypeScript, Go, Java, .NET, Ruby, and Rust. Use when the user is building workflows, activities, or workers with a Temporal SDK, debugging issues like non-determinism errors, stuck workflows, or activity retries, using Temporal CLI, Temporal Server, or Temporal Cloud, 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".

— the description by Temporal

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Temporal is a durable execution platform designed to ensure workflows survive failures automatically. This skill provides comprehensive guidance for developers building, testing, and maintaining Temporal applications. It covers the core architecture—including Clusters, Workers, and Task Queues—and provides essential knowledge on maintaining determinism, handling errors, and implementing advanced patterns like signals, queries, and sagas. The skill supports development across Python, TypeScript, Go, Java, .NET, Ruby, and Rust, offering specific references for each language.

What it does

Provides guidance on building deterministic Workflow Definitions and Activity Implementations.
Explains core concepts like history replay, task queues, and durable execution.
Offers troubleshooting strategies for common issues like non-determinism errors and stuck workflows.
Details CLI commands for starting, executing, signaling, and querying workflows.
Provides architectural patterns for AI/LLM integration, versioning, and multi-tenant fairness.
Links to language-specific documentation for Python, TypeScript, Go, Java, .NET, Ruby, and Rust.

When to use it

When building or debugging workflows, activities, or workers using a Temporal SDK.
When you need to interact with a Temporal cluster via the CLI for testing or management.
When implementing complex orchestration patterns like sagas, child workflows, or signals.
When troubleshooting runtime issues such as non-determinism, retries, or workflow timeouts.
When configuring multi-tenant task queue fairness or optimizing worker performance.

Advantages

Ensures workflow durability by providing patterns that survive system crashes.
Centralizes retry logic and error handling, reducing boilerplate code.
Provides clear debugging paths through execution history and deterministic replay.
Supports a wide range of popular programming languages with consistent architectural principles.
Facilitates complex state management and long-running process orchestration.

Usage examples

“How do I start a new workflow from the command line?”: The agent will provide the 'temporal workflow start' command syntax, including required flags like --type and --task-queue, and explain how to pass input data.
“I am getting a non-determinism error in my workflow. How do I fix it?”: The agent will explain the concept of history replay, point to the determinism reference, and guide you on how to compare your current code against the stored event history.
“How should I handle LLM API calls within a Temporal workflow?”: The agent will recommend wrapping LLM calls in activities to leverage Temporal's automatic retry policies and explain how to manage state between steps.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/openai/temporal-developer/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip temporal-developer.zip -d .agents/skills

Documentation by Temporal

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.

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:

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

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

Workflow Code	Command	Event
Execute activity	`ScheduleActivityTask`	`ActivityTaskScheduled`
Sleep/timer	`StartTimer`	`TimerStarted`
Child workflow	`StartChildWorkflowExecution`	`ChildWorkflowExecutionStarted`

See references/core/determinism.md for detailed explanation.

Getting Started

Ensure Temporal CLI is installed

Check if temporal CLI is installed. If not, follow the instructions at references/core/install_cli.md to install it for your platform.

Read All Relevant References

First, read the getting started guide for the language you are working in:
- Python -> read references/python/python.md
- TypeScript -> read references/typescript/typescript.md
- Go -> read references/go/go.md
- Java -> read references/java/java.md
- .NET (C#) -> read references/dotnet/dotnet.md
- Ruby -> read references/ruby/ruby.md
- Rust -> read references/rust/rust.md (in Public Preview)
Second, read appropriate core and language-specific references for the task at hand.

Primary References

references/core/determinism.md - Why determinism matters, replay mechanics, basic concepts of activities
- Language-specific info at references/{your_language}/determinism.md
references/core/patterns.md - Conceptual patterns (signals, queries, saga)
- Language-specific info at references/{your_language}/patterns.md
references/core/gotchas.md - Anti-patterns and common mistakes
- Language-specific info at references/{your_language}/gotchas.md
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
references/core/standalone-activities.md - Standalone Activities: run an Activity directly from a Client without a Workflow (Public Preview)
- Language-specific info at references/{your_language}/standalone-activities.md
references/core/troubleshooting.md - Decision trees, recovery procedures
references/core/error-reference.md - Common error types, workflow status reference
references/core/interactive-workflows.md - Testing signals, updates, queries
references/core/dev-management.md - Dev cycle & management of server and workers
references/core/cli-workflow-commands.md - Developer-facing CLI commands for workflow interaction (start, execute, signal, query, update)
references/core/ai-patterns.md - AI/LLM pattern concepts
- Language-specific info at references/{your_language}/ai-patterns.md, if available. Currently Python only.

Task Queue Priority and Fairness

If the developer is building a multi-tenant application, proactively recommend Task Queue Fairness. Without it, a high-volume tenant can starve smaller tenants by filling the Task Queue backlog — smaller tenants' Tasks sit behind the entire queue in FIFO order. Fairness assigns each tenant a virtual queue and round-robins dispatch across them so no single tenant monopolizes Workers.

Priority and Fairness also apply to tiered workloads (batch vs. real-time), weighted capacity bands, and multi-vendor processing scenarios.

references/core/priority-fairness.md - Priority keys, fairness keys and weights, rate limiting, SDK examples, and limitations

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 references/integrations.md — 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.

Files

ATTRIBUTION.mdAdded by AutoGineer900 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md7.4 KiB
references/core/ai-patterns.md5.5 KiB
references/core/cli-workflow-commands.md9.8 KiB
references/core/determinism.md6.4 KiB
references/core/dev-management.md4.2 KiB
references/core/error-reference.md3.0 KiB
references/core/gotchas.md9.3 KiB
references/core/install_cli.md1.3 KiB
references/core/interactive-workflows.md1.3 KiB
references/core/patterns.md14.7 KiB
references/core/priority-fairness.md10.2 KiB
references/core/standalone-activities.md8.1 KiB
references/core/troubleshooting.md9.2 KiB
references/core/versioning.md8.8 KiB
references/dotnet/advanced-features.md6.6 KiB
references/dotnet/data-handling.md5.7 KiB
references/dotnet/determinism-protection.md2.7 KiB
references/dotnet/determinism.md2.6 KiB
references/dotnet/dotnet.md8.5 KiB
references/dotnet/error-handling.md4.5 KiB
references/dotnet/gotchas.md7.3 KiB
references/dotnet/observability.md3.1 KiB
references/dotnet/patterns.md13.9 KiB
references/dotnet/standalone-activities.md6.0 KiB
references/dotnet/testing.md5.7 KiB
references/dotnet/versioning.md11.5 KiB
references/go/advanced-features.md6.1 KiB
references/go/data-handling.md7.6 KiB
references/go/determinism-protection.md3.3 KiB
references/go/determinism.md3.0 KiB
references/go/error-handling.md5.6 KiB
references/go/go.md7.7 KiB
references/go/gotchas.md7.4 KiB
references/go/observability.md5.4 KiB
references/go/patterns.md15.7 KiB
references/go/standalone-activities.md6.5 KiB
references/go/testing.md6.4 KiB
references/go/versioning.md9.7 KiB
references/integrations.md5.1 KiB
references/java/advanced-features.md6.5 KiB
references/java/data-handling.md8.8 KiB
references/java/determinism-protection.md3.4 KiB
references/java/determinism.md3.4 KiB
references/java/error-handling.md6.1 KiB
references/java/gotchas.md5.4 KiB
references/java/integrations/spring-ai.md12.7 KiB
references/java/integrations/spring-boot.md10.0 KiB
references/java/java.md10.0 KiB
references/java/observability.md4.1 KiB
references/java/patterns.md14.7 KiB
references/java/standalone-activities.md5.3 KiB
references/java/testing.md7.8 KiB
references/java/versioning.md11.1 KiB
references/python/advanced-features.md7.0 KiB
references/python/ai-patterns.md10.3 KiB
references/python/data-handling.md6.2 KiB
references/python/determinism-protection.md6.9 KiB
references/python/determinism.md2.0 KiB
references/python/error-handling.md4.1 KiB
references/python/gotchas.md7.3 KiB
references/python/integrations/braintrust.md7.2 KiB
references/python/integrations/google-adk.md10.5 KiB
references/python/integrations/langgraph.md8.2 KiB
references/python/integrations/langsmith.md9.3 KiB
references/python/integrations/openai-agents-sdk.md20.1 KiB
references/python/integrations/opentelemetry.md2.7 KiB
references/python/integrations/pydantic-ai.md11.3 KiB
references/python/observability.md3.2 KiB
references/python/patterns.md12.1 KiB
references/python/python.md8.0 KiB
references/python/standalone-activities.md5.8 KiB
references/python/sync-vs-async.md7.1 KiB
references/python/testing.md4.9 KiB
references/python/versioning.md12.6 KiB
references/python/workflow-streams.md21.4 KiB
references/ruby/advanced-features.md7.8 KiB
references/ruby/data-handling.md3.9 KiB
references/ruby/determinism-protection.md5.1 KiB
references/ruby/determinism.md2.9 KiB
references/ruby/error-handling.md2.7 KiB
references/ruby/gotchas.md6.9 KiB
references/ruby/observability.md2.2 KiB
references/ruby/patterns.md10.2 KiB
references/ruby/ruby.md6.1 KiB
references/ruby/testing.md6.5 KiB
references/ruby/versioning.md8.8 KiB
references/rust/rust.md6.8 KiB
references/typescript/advanced-features.md5.6 KiB
references/typescript/data-handling.md5.9 KiB
references/typescript/determinism-protection.md2.4 KiB
references/typescript/determinism.md2.1 KiB
references/typescript/error-handling.md3.3 KiB
references/typescript/gotchas.md9.1 KiB
references/typescript/integrations/braintrust.md3.7 KiB
references/typescript/integrations/mastra.md7.5 KiB
references/typescript/integrations/opentelemetry.md3.6 KiB
references/typescript/integrations/vercel-ai-sdk.md8.4 KiB
references/typescript/observability.md3.7 KiB
references/typescript/patterns.md11.4 KiB
references/typescript/standalone-activities.md5.8 KiB
references/typescript/testing.md6.1 KiB
references/typescript/typescript.md7.4 KiB
references/typescript/versioning.md9.2 KiB

references/core/troubleshooting.md

Temporal Troubleshooting Guide

Workflow Diagnosis Decision Tree

Workflow not behaving as expected?
│
├─▶ What is the workflow status?
│   │
│   ├─▶ RUNNING (but no progress)
│   │   └─▶ Go to: "Workflow Stuck" section
│   │
│   ├─▶ FAILED
│   │   └─▶ Go to: "Workflow Failed" section
│   │
│   ├─▶ TIMED_OUT
│   │   └─▶ Go to: "Timeout Issues" section
│   │
│   └─▶ COMPLETED (but wrong result)
│       └─▶ Go to: "Wrong Result" section

Workflow Stuck (RUNNING but No Progress)

Decision Tree

Workflow stuck in RUNNING?
│
├─▶ Is a worker running?
│   │
│   ├─▶ NO: Start a worker
│   │   └─▶ See references/core/dev-management.md
│   │
│   └─▶ YES: Is it on the correct task queue?
│       │
│       ├─▶ NO: Start worker with correct task queue
│       │
│       └─▶ YES: Check for non-determinism
│           │
│           ├─▶ NondeterminismError in logs?
│           │   └─▶ Go to: "Non-Determinism" section
│           │
│           ├─▶ Check history for task failures
│           │   └─▶ Run: `temporal workflow show --workflow-id <id>`
│           │       │
│           │       ├─▶ WorkflowTaskFailed event?
│           │       │   └─▶ Check error type in event details
│           │       │       └─▶ Go to relevant section in error-reference.md
│           │       │
│           │       └─▶ ActivityTaskFailed event?
│           │           └─▶ Go to: "Activity Keeps Retrying" section
│           │
│           └─▶ No errors in logs or history?
│               └─▶ Check if workflow is waiting for signal/timer

Common Causes

No worker running
- See references/core/dev-management.md
Worker on wrong task queue
- Check: Worker logs for task queue name
- Fix: Start worker with matching task queue
Worker has stale code
- Check: Worker startup time vs code changes
- Fix: Restart worker with updated code
Workflow waiting for signal
- Check: Workflow history for pending signals
- Fix: Send expected signal or check signal sender
Activity stuck/timing out
- Check: Activity retry attempts in history
- Fix: Investigate activity failure, increase timeout

Non-Determinism Errors

Decision Tree

NondeterminismError?
│
├─▶ Was code intentionally changed?
│   │
│   ├─▶ YES: Do you need to support in-flight workflows?
│   │   │
│   │   ├─▶ YES (production): Use patching API
│   │   │   └─▶ See: references/core/versioning.md
│   │   │
│   │   └─▶ NO (local dev/testing): Terminate or reset workflow
│   │       └─▶ `temporal workflow terminate --workflow-id <id>`
│   │       └─▶ Then start fresh with new code
│   │
│   └─▶ NO: Accidental change
│       │
│       ├─▶ Can you identify the change?
│       │   │
│       │   ├─▶ YES: Revert and restart worker. Note, this doesn't always work if workflow has progressed past the change (may induce other code paths), so may need to reset workflow.
│       │   │
│       │   └─▶ NO: Compare current code to expected history
│       │       └─▶ Check: Activity names, order, parameters

Common Causes

Changed call order

# Before           # After (BREAKS)
await activity_a   await activity_b
await activity_b   await activity_a

Changed call name

# Before                    # After (BREAKS)
await process_order(...)    await handle_order(...)

Added/removed call
- Adding new activity mid-workflow
- Removing activity that was previously called
Using non-deterministic code
- datetime.now() in workflow (use workflow.now())
- random.random() in workflow (use workflow.random())

Recovery

Accidental Change:

Identify the change
Revert code to match history
Restart worker
Workflow automatically recovers

Intentional Change:

Use patching API for gradual migration
Or terminate old workflows, start new ones

Workflow Failed

Decision Tree

Workflow status = FAILED?
│
├─▶ Check workflow error message
│   │
│   ├─▶ Application error (your code)
│   │   └─▶ Fix the bug, start new workflow
│   │
│   ├─▶ NondeterminismError
│   │   └─▶ Go to: "Non-Determinism" section
│   │
│   └─▶ Timeout error
│       └─▶ Go to: "Timeout Issues" section

Common Causes

Unhandled exception in workflow
- Check error message and stack trace
- Fix bug in workflow code
Activity exhausted retries
- All retry attempts failed
- Check activity logs for root cause
Non-retryable error thrown
- Error marked as non-retryable
- Intentional failure, check business logic

Timeout Issues

Timeout Types

Timeout	Scope	What It Limits
`WorkflowExecutionTimeout`	Entire workflow	Total time including retries and continue-as-new
`WorkflowRunTimeout`	Single run	Time for one run (before continue-as-new)
`ScheduleToCloseTimeout`	Activity	Total time including retries
`StartToCloseTimeout`	Activity	Single attempt time
`HeartbeatTimeout`	Activity	Time between heartbeats

Diagnosis

Timeout error?
│
├─▶ Which timeout?
│   │
│   ├─▶ Workflow timeout
│   │   └─▶ Increase timeout or optimize workflow. Better yet, consider removing the workflow timeout, as it is generally discouraged unless *necessary* for your use case.
│   │
│   ├─▶ ScheduleToCloseTimeout
│   │   └─▶ Activity taking too long overall (including retries)
│   │
│   ├─▶ StartToCloseTimeout
│   │   └─▶ Single activity attempt too slow
│   │
│   └─▶ HeartbeatTimeout
│       └─▶ Activity not heartbeating frequently enough
│           └─▶ Add heartbeat() calls in long activities

Fixes

Increase timeout if operation legitimately takes longer
Add heartbeats to long-running activities
Optimize activity to complete faster
Break into smaller activities for better granularity

Activity Keeps Retrying

Decision Tree

Activity retrying repeatedly?
│
├─▶ Check activity error
│   │
│   ├─▶ Transient error (network, timeout)
│   │   └─▶ Expected behavior, will eventually succeed
│   │
│   ├─▶ Permanent error (bug, invalid input)
│   │   └─▶ Fix the bug or mark as non-retryable
│   │
│   └─▶ Resource exhausted
│       └─▶ Add backoff, check rate limits

Common Causes

Bug in activity code
- Fix the bug
- Consider marking certain errors as non-retryable
External service down
- Retries are working as intended
- Monitor service recovery
Invalid input
- Validate inputs before activity
- Return non-retryable error for bad input

Wrong Result (Completed but Incorrect)

Diagnosis

Check workflow history for unexpected activity results
Verify activity implementations produce correct output
Check for race conditions in parallel execution
Verify signal handling if signals are involved

Common Causes

Activity bug - Wrong logic in activity
Stale data - Activity using outdated information
Signal ordering - Signals processed in unexpected order
Parallel execution - Race condition in concurrent operations

Worker Issues

Worker Not Starting

Worker won't start?
│
├─▶ Connection error
│   └─▶ Check Temporal server is running
│       └─▶ `temporal server start-dev` (start in background, see references/core/dev-management.md)
│
├─▶ Registration error
│   └─▶ Check workflow/activity definitions are valid
│
└─▶ Other errors (imports, etc.)
    └─▶ Debug those errors as usual.

Worker Crashing

Out of memory - Reduce concurrent tasks, check for leaks
Unhandled exception - Add error handling
Dependency issue - Check package versions

Useful Commands

# Check Temporal server
temporal server start-dev

# List workflows
temporal workflow list

# Describe specific workflow
temporal workflow describe --workflow-id <id>

# Show workflow history
temporal workflow show --workflow-id <id>

# Terminate stuck workflow
temporal workflow terminate --workflow-id <id>

# Reset workflow to specific point
temporal workflow reset --workflow-id <id> --event-id <event-id>

Quick Reference: Status → Action

Status	First Check	Common Fix
RUNNING (stuck)	Worker running?	Start/restart worker
FAILED	Error message	Fix bug, handle error
TIMED_OUT	Which timeout?	Increase timeout or optimize
TERMINATED	Who terminated?	Check audit log
CANCELED	Cancellation source	Expected or investigate

Requirements and compatibility

Written for: OpenAI Codex

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Temporal

Publisher

OpenAI (Official)

Distributed by

OpenAI

Source

openai/plugins · plugins/temporal/skills/temporal-developer · commit d420d13

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from plugins/temporal/LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by Temporal or OpenAI.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download temporal-developer.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Temporal

Skill: temporal-developer

Overview

Core Architecture

History Replay: Why Determinism Matters

Getting Started

Ensure Temporal CLI is installed

Read All Relevant References

Primary References

Task Queue Priority and Fairness

Additional Topics

Third-Party Integrations

Feedback

Reporting Issues in This Skill

Files

references/core/troubleshooting.md

Temporal Troubleshooting Guide

Workflow Diagnosis Decision Tree

Workflow Stuck (RUNNING but No Progress)

Decision Tree

Common Causes

Non-Determinism Errors

Decision Tree

Common Causes

Recovery

Workflow Failed

Decision Tree

Common Causes

Timeout Issues

Timeout Types

Diagnosis

Fixes

Activity Keeps Retrying

Decision Tree

Common Causes

Wrong Result (Completed but Incorrect)

Diagnosis

Common Causes

Worker Issues

Worker Not Starting

Worker Crashing

Useful Commands

Quick Reference: Status → Action

See Also

Requirements and compatibility

Security

Attribution and licence

Related skills

Implement Spec

MCP Builder

Schema

Postgresql Table Design

SQL Optimization Patterns

API Scaffolding Fastapi Pro

Download ZIP