temporal
Build durable, distributed workflows using Temporal to ensure fault tolerance.
Install
mkdir -p .claude/skills/temporal && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/17119" && unzip -o skill.zip -d .claude/skills/temporal && rm skill.zipInstalls to .claude/skills/temporal
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Build reliable distributed workflows with Temporal. Use when a user asks to orchestrate microservices, handle long-running workflows, implement saga patterns, build reliable background jobs, or create fault-tolerant distributed systems.Key capabilities
- →Build reliable distributed workflows
- →Orchestrate microservices with fault tolerance
- →Implement saga patterns for long-running processes
- →Create reliable background jobs
- →Define workflows that survive crashes and automatically retry
- →Interact with external services through activities
How it works
This skill provides code examples and guidelines for building reliable distributed workflows using Temporal, which ensures exactly-once execution and fault tolerance.
Inputs & outputs
When to use temporal
- →Implement a saga pattern
- →Orchestrate microservices
- →Build reliable background tasks
About this skill
Temporal
Overview
A Temporal application has three parts. The Temporal Service stores each workflow's event history. A Worker (your process) runs workflow code and activities, polling a task queue. A Client starts workflows and sends them signals and queries. Workflow code must be deterministic (it is replayed from history): do no I/O, randomness or Date.now() in it; put all side effects in activities. Activities are retried automatically but can run more than once, so make them idempotent. This skill uses the TypeScript SDK (@temporalio/* 1.24).
Instructions
Step 1: Run a local server and create the project
brew install temporal # or download the CLI from the temporalio/cli GitHub releases and verify checksums.txt
temporal server start-dev --ip 127.0.0.1 # gRPC on 7233, Web UI on http://localhost:8233, in-memory unless --db-filename is given
mkdir orders && cd orders && npm init -y
npm install @temporalio/client @temporalio/worker @temporalio/workflow @temporalio/activity
npm install -D typescript tsx @types/node
npx @temporalio/create@latest orders --sample hello-world scaffolds a similar project. For production use Temporal Cloud or a self-hosted cluster; start-dev is for development only.
Step 2: Workflow
The workflow reserves stock, charges the customer, waits for a signal from the warehouse (with a two-hour timeout) and compensates with a refund when the signal never arrives.
// src/types.ts
export interface Item { sku: string; price: number; quantity: number }
export interface OrderResult { orderId: string; tracking: string; total: number }
// src/workflows.ts
import { proxyActivities, defineSignal, setHandler, condition } from '@temporalio/workflow'
import type * as activities from './activities'
import type { Item, OrderResult } from './types'
type Activities = typeof activities
const { reserveInventory, processPayment, refundPayment, shipOrder, sendConfirmation } =
proxyActivities<Activities>({
startToCloseTimeout: '30 seconds',
retry: { maximumAttempts: 3 },
})
export const warehouseConfirmed = defineSignal('warehouseConfirmed')
export async function orderWorkflow(orderId: string, items: Item[]): Promise<OrderResult> {
let confirmed = false
setHandler(warehouseConfirmed, () => { confirmed = true })
const reservation = await reserveInventory(orderId, items)
const payment = await processPayment(orderId, reservation.total)
// Durable wait: up to 2 hours for the warehouse signal, no worker resources held
if (!(await condition(() => confirmed, '2 hours'))) {
await refundPayment(payment.chargeId)
throw new Error(`warehouse did not confirm order ${orderId}`)
}
const tracking = await shipOrder(orderId)
await sendConfirmation(orderId, tracking)
return { orderId, tracking, total: reservation.total }
}
Import activities only as types (import type) in workflow files; importing the implementation breaks the workflow sandbox. condition(fn, timeout) returns false on timeout. Use sleep('2 hours') from @temporalio/workflow for a plain durable timer; never setTimeout.
Step 3: Activities
// src/activities.ts
import type { Item } from './types'
export async function reserveInventory(orderId: string, items: Item[]) {
const total = items.reduce((sum, i) => sum + i.price * i.quantity, 0)
return { reservationId: `res_${orderId}`, total }
}
export async function processPayment(orderId: string, amount: number) {
// Pass orderId as the payment provider's idempotency key: activities can run more than once
console.log(`charging ${amount} for ${orderId}`)
return { chargeId: `ch_${orderId}` }
}
export async function refundPayment(chargeId: string) {
console.log(`refunding ${chargeId}`)
}
export async function shipOrder(orderId: string) {
return `TRK-${orderId}`
}
export async function sendConfirmation(orderId: string, tracking: string) {
console.log(`order ${orderId} shipped, tracking ${tracking}`)
}
Real activities call your payment provider or database; pass a stable key such as the order id as the provider's idempotency key so a retry cannot charge twice. Throw ApplicationFailure.nonRetryable(...) (exported by @temporalio/activity) for errors that retrying cannot fix.
Step 4: Worker and client
// src/worker.ts
import { Worker } from '@temporalio/worker'
import * as activities from './activities'
async function main() {
const worker = await Worker.create({
workflowsPath: require.resolve('./workflows'),
activities,
taskQueue: 'orders',
})
await worker.run()
}
main().catch((err) => { console.error(err); process.exit(1) })
// src/client.ts
import { Client } from '@temporalio/client'
import { orderWorkflow, warehouseConfirmed } from './workflows'
async function main() {
const client = new Client() // localhost:7233, namespace "default"
const handle = await client.workflow.start(orderWorkflow, {
taskQueue: 'orders',
workflowId: 'order-A-1001',
args: ['A-1001', [{ sku: 'KB-75', price: 89.5, quantity: 2 }]],
})
console.log('started', handle.workflowId)
await handle.signal(warehouseConfirmed)
console.log('result', await handle.result())
}
main().catch((err) => { console.error(err); process.exit(1) })
Run the worker (npx tsx src/worker.ts) in one terminal and the client (npx tsx src/client.ts) in another. Nothing runs without a worker polling the same task queue. Inspect from the CLI:
$ temporal workflow list
Status WorkflowId Type StartTime
Completed order-A-1001 orderWorkflow 7 seconds ago
$ temporal workflow show -w order-A-1001
Examples
Example 1: "Charge a card, ship, and refund if the warehouse never answers"
Request: "If the warehouse has not confirmed within two hours, refund and fail the order."
Steps: use the workflow above. Start it with the client; do not send the signal. After two hours the timer fires, refundPayment runs and the workflow fails (the timeout branch was not run here, only the signal path) with warehouse did not confirm order A-1001.
Example 2: "Confirm the order from my API"
Request: "My webhook should tell a running order the warehouse is ready."
Steps: in the webhook handler get a handle with client.workflow.getHandle('order-A-1001') and call await handle.signal(warehouseConfirmed). Result: the workflow continues to shipOrder and returns { orderId: 'A-1001', tracking: 'TRK-A-1001', total: 179 }. This exact flow was run against temporal server start-dev.
Guidelines
- Workflow ids are unique per namespace for running workflows: derive them from a business key (
order-A-1001) so a duplicate request cannot start a second run. - Activities are at-least-once, not exactly-once; workflow state is what is durable. Design activities to be idempotent.
- Keep workflow history bounded: for loops that run indefinitely use
continueAsNew. - When you change workflow code that has running executions, use the SDK's patching (
patched) or worker versioning, or replays will fail with non-determinism errors. - Set
startToCloseTimeouton every activity; for long ones add heartbeats. - Do not use Temporal for a simple cron job or a one-shot task a queue can handle; it pays off for multi-step, stateful or long-lived processes.
temporal server start-devhas no authentication; bind it to 127.0.0.1 and never expose it.
When not to use it
- →When the user needs to implement simple cron jobs
- →When the user needs to build systems that do not require stateful, long-running workflows
- →When the user needs to interact with the outside world directly from workflows
Limitations
- →Temporal is designed for complex, stateful workflows, not simple cron jobs
- →Activities are the only way to interact with the outside world from workflows
- →Workflows are defined in specific programming languages like TypeScript, Go, Python, Java, .NET
How it compares
This workflow provides a durable execution platform for complex, stateful distributed systems, contrasting with simpler task queues or manual retry logic.
Compared to similar skills
temporal side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| temporal (this skill) | 0 | 6mo | Review | Advanced |
| architecture-patterns | 55 | 6mo | No flags | Advanced |
| ark-analysis | 0 | 7mo | Review | Beginner |
| backend-expert | 0 | 5mo | No flags | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by TerminalSkills
View all by TerminalSkills →You might also like
architecture-patterns
wshobson
Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use when architecting complex backend systems or refactoring existing applications for better maintainability.
ark-analysis
mckinsey
Analyze the Ark codebase by cloning the repository to a temporary location. Use this skill when the user asks questions about how Ark works, wants to understand Ark's implementation, or needs to examine Ark source code.
backend-expert
FlavioProgramador
Advanced backend engineering guidelines focusing on clean architecture, API standards, performance, asynchronous jobs, and clean code principles.
workflow-orchestration-patterns
wshobson
Design durable workflows with Temporal for distributed systems. Covers workflow vs activity separation, saga patterns, state management, and determinism constraints. Use when building long-running processes, distributed transactions, or microservice orchestration.
auth-http-api-cloudbase
TencentCloudBase
Use when you need to implement CloudBase Auth v2 over raw HTTP endpoints (login/signup, tokens, user operations) from backends or scripts that are not using the Web or Node SDKs.
generating-grpc-services
jeremylongshore
Generate gRPC service definitions, stubs, and implementations from Protocol Buffers. Use when creating high-performance gRPC services. Trigger with phrases like "generate gRPC service", "create gRPC API", or "build gRPC server".