Temporal Skill for Claude Code

A comprehensive Claude Code skill for working with Temporal.io across multiple SDK languages. This skill helps Claude assist developers in building reliable, distributed applications with Temporal.

What is this?

This repository contains a single Temporal skill for Claude Code with SDK-specific resources for each programming language. The skill provides:

Unified Temporal concepts and best practices
SDK-specific guidance as resources (Java, Python, TypeScript, Go, .NET, PHP)
Curated links to official Temporal documentation
Framework integration guidance (e.g., Spring Boot for Java)
Sample code references and patterns

Architecture

Single Skill with SDK Resources:

src/temporal.md - Main skill file with core Temporal concepts
src/sdks/java/ - Java SDK resource with Spring Boot integration
src/sdks/python/ - Python SDK resource with FastAPI/Django integration
src/sdks/typescript/ - (Coming soon) TypeScript SDK resource
...and more

When you use the skill, Claude references the appropriate SDK resource based on your language.

Quick Start

For Claude Code Users

Option 1: Use the pre-built package

Download the latest skill package from the releases

Extract the contents:

unzip temporal-skill-latest.zip
cd temporal-skill

Copy to your Claude skills directory:

cp temporal.md ~/.claude/skills/
cp -r sdks ~/.claude/skills/

Start using Claude Code - reference the skill in your prompts

Option 2: Copy directly (for development)

# Copy the skill and SDK resources
cp src/temporal.md ~/.claude/skills/
cp -r src/sdks ~/.claude/skills/

# Or if Claude Code is configured differently:
cp src/temporal.md .claude/skills/
cp -r src/sdks .claude/skills/

For Claude Cloud Users

Build the skill package:
```
./build-skill-package.sh
```
Upload the generated package to Claude Cloud:
```
dist/temporal-skill-latest.zip
```
Activate the skill in your Cloud project

Usage Examples

You: "Create a Temporal workflow in Java that processes orders with retry logic"

Claude: [Uses the temporal skill to understand the request, references the Java SDK
         resource, fetches latest SDK version, generates proper workflow/activity
         interfaces, implements retry policies, creates worker and client code]

You: "How do I implement signals in Temporal?"

Claude: [References temporal.md for signal concepts, then provides language-specific
         examples from your SDK resource]

You: "Set up a new Temporal project with Spring Boot"

Claude: [References Java SDK resource's Spring Boot integration guide, provides
         dependencies, configuration, and project structure]

What the Skill Provides

When you ask Claude about Temporal with this skill installed, Claude can help you with:

SDK Selection: Help you choose the right SDK for your project
Getting Started: Set up new Temporal projects with proper dependency configuration
Core Concepts: Understand workflows, activities, workers, and clients
Framework Integration: Implement framework-specific patterns (Spring Boot, etc.)
Advanced Patterns: Implement signals, queries, sagas, child workflows, and more
Testing: Write unit and integration tests for your workflows
Best Practices: Follow Temporal's recommended patterns and avoid common pitfalls
Sample Discovery: Find relevant examples from official samples repositories
Latest Versions: Automatically fetch and use the newest SDK versions

Repository Structure

.
├── src/
│   ├── temporal.md              # Main skill file
│   └── sdks/
│       ├── java/                # Java SDK resource
│       │   ├── java.md          # Java SDK guide
│       │   └── references/      # Additional references
│       │       ├── samples.md   # Samples catalog
│       │       └── spring-boot.md # Spring Boot guide
│       └── python/              # Python SDK resource
│           ├── python.md        # Python SDK guide
│           └── references/      # Additional references
│               ├── samples.md   # Samples catalog
│               └── framework-integration.md # FastAPI/Django/Flask
├── test/
│   ├── java/
│   │   └── skill-integration/   # Java integration tests
│   └── python/
│       └── skill-integration/   # Python integration tests
├── build-skill-package.sh       # Build script
├── BUILD.md                     # Build documentation
└── README.md                    # This file

Current SDK Resources

Java SDK

Status: ✅ Complete
Location: src/sdks/java/java.md
Features:

Complete Java SDK reference guide
Maven/Gradle dependency management
Spring Boot integration patterns
Comprehensive samples catalog
Testing strategies

Python SDK

Status: ✅ Complete
Location: src/sdks/python/python.md
Features:

Complete Python SDK reference guide
Poetry/pip dependency management
FastAPI/Django/Flask integration patterns
Comprehensive samples catalog (42+ samples)
Testing strategies with pytest
Async/await patterns and best practices

TypeScript SDK

Status: 🚧 Planned
Location: src/sdks/typescript/typescript.md (Coming soon)

Go SDK

Status: ✅ Complete
Location: src/sdks/go/go.md
Features:

Complete Go SDK reference guide
Go module dependency management
Workflow determinism rules and alternatives
Activity registration patterns
Versioning patterns and cleanup process
Comprehensive samples catalog
Testing strategies with testsuite
Production best practices

.NET SDK

Status: 🚧 Planned
Location: src/sdks/dotnet/dotnet.md (Coming soon)

PHP SDK

Status: 🚧 Planned
Location: src/sdks/php/php.md (Coming soon)

Building the Skill Package

The build system creates a single production-ready package:

# Build the skill package
./build-skill-package.sh

# Build without URL validation (faster)
./build-skill-package.sh --skip-url-check

Output:

dist/
├── temporal-skill-YYYYMMDD_HHMMSS.zip  # Timestamped package
├── temporal-skill-latest.zip            # Symlink to latest
└── build-report.txt                     # Build validation report

See BUILD.md for detailed build documentation.

Testing

Integration tests validate the skills work end-to-end in the actual Claude Code workflow.

Prerequisites

claude-code CLI: npm install -g @anthropic-ai/claude-code
Anthropic API Key: Set as ANTHROPIC_API_KEY environment variable

Unified Test Runner

The repository provides a unified test runner at the root that supports all SDK implementations:

# Set your Anthropic API key
export ANTHROPIC_API_KEY='your-api-key-here'

# Test Java SDK (standard)
./test-skill.sh Java

# Test Java SDK (Spring Boot variant)
./test-skill.sh Java --variant spring-boot

# Test Python SDK
./test-skill.sh Python

# Validation only (skip execution tests)
./test-skill.sh Java --skip-execution
./test-skill.sh Python --skip-execution

Run ./test-skill.sh --help for all available options and supported SDKs.

Testing All SDKs

To test all SDKs sequentially:

export ANTHROPIC_API_KEY='your-api-key-here'

# Run all tests
./test-skill.sh Java
./test-skill.sh Java --variant spring-boot
./test-skill.sh Python

Direct SDK Test Scripts

SDK-specific test scripts can still be run directly if needed:

# Java standard
cd test/java/skill-integration && ./run-integration-test.sh

# Java Spring Boot
cd test/java/skill-integration && ./run-spring-boot-test.sh

# Python
cd test/python/skill-integration && ./run-integration-test.sh

What the Tests Do

The integration tests:

Install the skill (temporal.md + sdks/) in a test workspace
Invoke claude-code CLI with a test prompt that triggers the skill
claude-code auto-loads the skill and generates a complete application
Validate the generated code structure and compilation
Optionally run the application with Temporal server

This proves the skill works correctly in the actual Claude Code user workflow and generates production-ready code.

See test READMEs for detailed documentation:

How It Works

Skill Architecture

The skill uses a unified architecture with SDK resources:

Main Skill: src/temporal.md provides core Temporal concepts and SDK selection
SDK Resources: Language-specific guides in src/sdks/<language>/<language>.md
Documentation-First: Points to official Temporal docs rather than duplicating content
Latest Versions: Fetches current SDK versions from package repositories
Sample Mapping: Maps use cases to relevant examples in official samples repositories
Pattern Library: Provides common patterns and best practices

Framework Intelligence

SDK resources include smart framework detection and guidance. For example, the Java SDK resource:

Asks if you want Spring Boot integration before proceeding
Uses appropriate dependencies and annotations for the chosen framework
Generates framework-specific configuration files
Leverages framework features like dependency injection

Development

Adding a New SDK Resource

To add support for a new Temporal SDK:

Create SDK directory:
```
mkdir -p src/sdks/newsdk
```

Create the SDK resource file:

# File should be named <sdk>.md
touch src/sdks/newsdk/newsdk.md

(Optional) Add SDK-specific references:
```
mkdir -p src/sdks/newsdk/references
```
Update src/temporal.md to mention the new SDK
Build and test:
```
./build-skill-package.sh
```

Modifying the Skill

Edit src/temporal.md for core Temporal concepts
Edit SDK resources in src/sdks/<language>/ for language-specific content

Run tests to validate (for Java SDK):

cd test/java/skill-integration
./run-integration-test.sh

Build the package:
```
./build-skill-package.sh
```

Best Practices

Keep URLs Current: Validate all documentation links regularly
Test SDK Variations: Run integration tests for SDK-specific features
Version Awareness: Ensure package repository links work correctly
Sample Updates: Keep sample references in sync with official repositories
Cross-SDK Consistency: Maintain similar structure across SDK resources

Requirements

For Using the Skill

Claude Code installed and configured
Basic understanding of Temporal concepts

For Building

Bash shell
curl or wget for URL validation

For Testing (Java SDK)

Anthropic API key (for automated tests)
Python 3 with anthropic package
Java 11+ and Maven
Temporal CLI (optional, for execution tests)

Contributing

Contributions are welcome! Areas for improvement:

New SDK Resources: Add resources for Python, TypeScript, Go, .NET, PHP
Additional Patterns: Add more advanced Temporal patterns to SDK resources
Sample Mapping: Improve use-case to sample mapping
Framework Examples: Expand framework integration guidance
Test Coverage: Add more test scenarios for existing SDKs
Documentation: Keep references current with Temporal updates

Contribution Workflow

Fork the repository
Create a new branch for your changes
Add/modify skill content or SDK resources
Run the integration tests (if applicable)
Build and validate the package
Submit a pull request

Support

For Skill Content

Main skill: Edit src/temporal.md
SDK-specific: Edit src/sdks/<sdk>/<sdk>.md
Check official Temporal docs: https://docs.temporal.io/

For Build Issues

See BUILD.md
Check dist/build-report.txt for details

For Test Issues

See SDK-specific test documentation
Review test workspace files for debugging

For Temporal Questions

Community forum: https://community.temporal.io/
GitHub: https://github.com/temporalio/
Slack: https://temporal.io/slack

Resources

Temporal Documentation: https://docs.temporal.io/
SDK Guides: https://docs.temporal.io/develop/
Samples Repositories: https://github.com/temporalio/samples-java (and others)
Community: https://community.temporal.io/
Temporal Learn: https://learn.temporal.io/

License

This skill package references official Temporal documentation and samples. Please refer to Temporal's licensing for their content.

Version

Current version: 1.0.0

Check dist/build-report.txt after building for package details.

mfateev/temporal-claude-skill