| name | temporal-developer |
| description | Develops Temporal apps in Python, TypeScript, Go, or Java: workflows, activities, workers, signals/queries/heartbeats, versioning, continue-as-new, sagas, and temporal CLI/dev server/Cloud. Use when building or debugging Temporal durable execution, including non-determinism and stuck workflows. Not for Inngest serverless events, n8n, or running temporal server start-dev as production. |
| version | 1.0.1 |
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, and Java.
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.
When to Use
Activate this skill when the user is:
- Building workflows, activities, or workers with any Temporal SDK (Python, TypeScript, Go, Java)
- Debugging non-determinism errors, stuck workflows, or activity retry failures
- Using Temporal CLI commands (
temporal workflow, temporal activity, temporal worker, etc.)
- Running or connecting to a Temporal dev server, self-hosted cluster, or Temporal Cloud
- Working with durable execution concepts: signals, queries, updates, heartbeats, versioning, continue-as-new, child workflows, saga patterns
- Implementing AI/LLM orchestration patterns on Temporal
Prerequisites
Ensure Temporal CLI is installed
Check if temporal CLI is installed:
temporal --version
If not installed, follow the platform-specific instructions below.
Windows (primary host)
- Determine your machine architecture (amd64 or arm64).
- Download the appropriate archive:
- Extract the downloaded archive.
- Add
temporal.exe to your PATH (e.g., copy to C:\Users\<you>\bin or a directory already on PATH).
macOS
brew install temporal
Linux
- Check your machine's architecture and download the appropriate archive:
- Extract the downloaded archive.
- Add the
temporal binary to your PATH (e.g., copy to /usr/local/bin).
Start a local dev server (for development)
temporal server start-dev
This starts a single-process dev server on the default address localhost:7233. The UI is available at http://localhost:8233. Do not use the dev server for production.
Read all relevant references
Before writing or debugging Temporal code, load the appropriate reference files:
- First, read the getting-started guide for the user's language:
- Python → read
references/python/python.md
- TypeScript → read
references/typescript/typescript.md
- Java → read
references/java/java.md
- Go → read
references/go/go.md
- Second, read the
core and language-specific references relevant to the task (see the Reference Loading Guide below).
Procedure
1. Identify the language and task type
Determine which Temporal SDK the user is working with (Python, TypeScript, Go, or Java) and what they are trying to accomplish (new workflow, debugging, versioning, etc.).
2. Load the appropriate references
Load reference files based on the task at hand. Always load the language getting-started guide first, then load topic-specific references as needed.
Core references (language-agnostic concepts)
| Reference file | When to load |
|---|
references/core/determinism.md | When explaining or debugging determinism, replay, or non-determinism errors. Also load the language-specific version at references/{lang}/determinism.md. |
references/core/patterns.md | When implementing signals, queries, saga patterns, or other workflow patterns. Also load references/{lang}/patterns.md. |
references/core/gotchas.md | When reviewing code for anti-patterns or common mistakes. Also load references/{lang}/gotchas.md. |
references/core/versioning.md | When changing workflow code that may affect running workflows. Also load references/{lang}/versioning.md. |
references/core/troubleshooting.md | When debugging stuck workflows, errors, or unexpected behavior. Use the decision trees and recovery procedures. |
references/core/error-reference.md | When the user encounters a specific error type or needs to understand workflow status meanings. |
references/core/interactive-workflows.md | When testing signals, updates, or queries against running workflows. |
references/core/dev-management.md | When managing the dev cycle — starting/stopping server, managing workers, iterating on code. |
references/core/ai-patterns.md | When building AI/LLM orchestration on Temporal. Also load references/{lang}/ai-patterns.md if available (currently Python only). |
Language-specific references
| Reference file | When to load |
|---|
references/{lang}/observability.md | When implementing logging, metrics, tracing, or debugging visibility for the user's language. |
references/{lang}/advanced-features.md | When the user needs language-specific guidance on advanced Temporal features. |
3. Write or debug workflow/activity code
Follow the determinism rules strictly:
- Workflow code must be deterministic. No direct API calls, no random numbers, no wall-clock time, no network I/O, no global mutable state.
- All side effects go in activities. Activities can fail, be retried, and have heartbeats.
- Use SDK-provided APIs for timers (
workflow.sleep / workflow.timer), activity invocation, child workflows, signals, queries, and continue-as-new.
4. Run the worker
Start the worker process for the user's language. The worker polls the specified Task Queue and executes workflow and activity code.
5. Start or signal workflows via CLI
Use Temporal CLI to start workflows, send signals, query state, or inspect history:
# Start a workflow
temporal workflow start --task-queue YOUR_TASK_QUEUE --type YOUR_WORKFLOW_TYPE --input '{"key":"value"}'
# Query a running workflow
temporal workflow query --workflow-id YOUR_WF_ID --query-type YOUR_QUERY_TYPE
# Send a signal
temporal workflow signal --workflow-id YOUR_WF_ID --signal-type YOUR_SIGNAL_TYPE --input '{"key":"value"}'
# Describe a workflow (see status and run info)
temporal workflow describe --workflow-id YOUR_WF_ID
# View event history
temporal workflow show --workflow-id YOUR_WF_ID
6. Debug non-determinism or stuck workflows
- Load
references/core/troubleshooting.md and references/core/error-reference.md.
- Load
references/core/determinism.md and references/{lang}/determinism.md.
- Use
temporal workflow show --workflow-id <ID> to inspect event history.
- Identify the event where replay diverges from generated commands.
- Fix the workflow code to be deterministic, or apply versioning if the change is intentional (load
references/core/versioning.md).
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 |
Pitfalls
- Never use wall-clock time, random numbers, or direct I/O inside workflow code. These break determinism and cause non-determinism errors on replay.
- Never mutate global state from workflow code. Replay will re-execute the workflow function; side effects on globals will compound.
- Do not use the dev server (
temporal server start-dev) for production. It is a single-process in-memory server with no persistence guarantees.
- Do not change workflow logic in a way that alters the command sequence for already-running workflows without a versioning strategy. Load
references/core/versioning.md and references/{lang}/versioning.md before making such changes.
- Activity retries are automatic. Do not wrap activity calls in manual retry loops inside workflows — use retry policies provided by the SDK.
- Heartbeat long-running activities. Without heartbeats, the server cannot detect a stalled activity and will not retry it until the activity timeout fires.
- Continue-as-new must be used before history grows too large. Event histories that grow without bound will eventually hit size limits and fail.
- Do not block workflow execution with synchronous waits. Use SDK async primitives (e.g.,
workflow.wait, asyncio in Python, Promise in TypeScript, Selector/Future in Go, CompletableFuture in Java).
Verification
Verify CLI installation
temporal --version
Expected: a version string is printed (e.g., temporal version 1.x.x).
Verify dev server is running
temporal operator cluster describe
Expected: cluster info is returned, including cluster name and server version. If the dev server is running on defaults, it connects to localhost:7233.
Verify a worker is polling
Start the worker process and check that it registers with the cluster:
temporal task-queue describe --task-queue YOUR_TASK_QUEUE
Expected: poller info is shown, indicating at least one poller is active for the task queue.
Verify a workflow completed successfully
temporal workflow describe --workflow-id YOUR_WF_ID
Expected: Status: COMPLETED in the output.
Verify event history for debugging
temporal workflow show --workflow-id YOUR_WF_ID
Expected: a chronological list of events. Look for WorkflowExecutionStarted, ActivityTaskScheduled, ActivityTaskStarted, ActivityTaskCompleted, WorkflowExecutionCompleted (or Failed).
Feedback
Prompt user for 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 development 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-developer/issues/new. Do not file the issue autonomously.
