Resonate Skills

Agent skills for building with Resonate — a durable execution platform for long-running, crash-safe workflows.

Each skill teaches a coding agent (Claude Code, Cursor, or any skill-aware agent) how to reason about and write Resonate code for a specific task: deploying servers, building HTTP services, implementing sagas, coordinating human-in-the-loop approvals, and more.

What's in this repo today

  • 12 foundational (language-agnostic) skills — concepts, mental models, the server-install guides, the ScyllaDB, NATS, and Postgres provider guides, the CLI reference, the cross-SDK defaults reference, the Temporal and DBOS migration playbooks, and the resonate-bash MCP tool guide that apply across every Resonate SDK.
  • 16 TypeScript per-SDK skills — idiomatic usage of the TypeScript SDK.
  • 8 Python per-SDK skills — basic usage + debugging + patterns (saga, recursive fan-out, human-in-the-loop, external system of record) + HTTP service design for the Python SDK.
  • 8 Rust per-SDK skills — basic usage + debugging + patterns (saga, recursive fan-out, durable-sleep-scheduled-work, human-in-the-loop, external system of record) for the early-development Rust SDK (v0.6.0, on crates.io); every Rust skill carries an explicit SDK-in-active-development note.
  • 8 Go per-SDK skills — basic usage (ephemeral + durable) + debugging + patterns (saga, recursive fan-out, durable-sleep, human-in-the-loop, external system of record) for the Go SDK, tagged 0.1.0 (install go get github.com/resonatehq/[email protected] — see the Go section below for why @latest doesn't resolve to it); every Go skill carries a version caveat and documents the direct Promises() / Schedules() sub-clients the 0.1.0 tag shipped.
  • 8 Java per-SDK skills — basic usage (ephemeral + durable) + debugging + patterns (saga, recursive fan-out, durable-sleep-scheduled-work, human-in-the-loop, external system of record) for the Java SDK. Unlike Go, the Java SDK is published on Maven Central (io.resonatehq:resonate-sdk-java:0.1.1) and ships the fuller surface — r.promises and r.schedules sub-clients plus a top-level r.schedule(...) cron API — so the Java skills use those directly rather than documenting a gap. Requires Java 21+ (virtual threads); every Java skill carries a light prerelease note (API may change before 1.0) and is compile-verified against 0.1.1.

That is 12 foundational + 48 per-SDK = 60 skills (16 TypeScript, 8 Python, 8 Rust, 8 Go, 8 Java).

What is a skill?

A skill is a directory with a SKILL.md file (and optional references/, scripts/, assets/). The frontmatter tells the agent when to load it:

---
name: resonate-saga-pattern-typescript
description: Implement saga patterns for distributed transactions with compensation logic. Use when coordinating multi-step processes that need to maintain consistency across failures by unwinding completed steps.
license: Apache-2.0
---

Skills follow Anthropic's Agent Skills convention and work with Claude Code, the Anthropic SDK, and other skill-aware tools.

Taxonomy

Every skill falls into one of two categories.

Foundational skills are language-agnostic. They teach concepts, mental models, or operational patterns that apply across every Resonate SDK. Their directory names carry no SDK suffix.

Per-SDK skills teach idiomatic usage of a specific Resonate SDK. Their directory names and frontmatter carry an SDK suffix: -typescript, -python, -rust, -go, or -java. When the same concept applies across SDKs (e.g. sagas, HTTP services, debugging), each SDK gets its own skill — the per-SDK version expresses the pattern in the SDK's natural idioms rather than translating mechanically.

Foundational

Start here:

  • resonate-philosophy — The foundational mindset. Read this first.
  • durable-execution — The core concept and Resonate's approach.
  • resonate-migrate-from-temporal — Coming from Temporal? Port your app pattern by pattern; maps temporalio/samples-* to Resonate examples across all four SDKs, with per-SDK API notes and honest coverage gaps.
  • resonate-migrate-from-dbos — Coming from DBOS? Port your app pattern by pattern; maps dbos-inc examples (demo apps + the SDK repos) to Resonate equivalents across all four SDKs, with per-SDK API notes and honest coverage gaps.

Operations:

  • resonate-cli — Drive the Resonate server from the shell: serve/dev, promise CRUD + search, schedules, invoke, tree, tasks, and the MCP shim. Covers every subcommand and flag as of resonate 0.9.8, plus the small set of docs-vs-binary deltas an agent will trip on.
  • resonate-server-deployment — Install and configure the Resonate server on Linux with systemd.
  • resonate-server-deployment-cloud-run — Deploy the Resonate server to Google Cloud Run with Cloud SQL Postgres storage.
  • resonate-server-scylladb — Run the protocol on ScyllaDB via resonate-on-scylladb, a separate Go server rather than a backend of the core server. Its own SCYLLADB_/SERVER_ env model (not RESONATE_), the six-table schema, the BUSL-1.1 constraint, and the current gaps. Drop-in: existing SDKs work unchanged.
  • resonate-server-nats — Run the protocol on NATS JetStream via resonate-on-nats, where NATS is both storage and transport and there is no HTTP interface at all. Partitioning across instances, wiring workers with the NatsNetwork client (TypeScript and Python only), the subject layout, the lowercase group/pid trap, and the current gaps.
  • resonate-server-postgres — Run the protocol inside Postgres via resonate-pg: one SQL file of stored procedures, no server process at all. Not the same thing as the core server on Postgres. The pg_cron timer dependency and its silent-failure mode, resonate_rpc, invoke's 24-hour default timeout, the resonate_worker grant surface, GC and id idempotency, the Deno-only client, and the current gaps. Apache 2.0, unlike the other two providers.
  • resonate-bash — Run shell scripts as durable, asynchronous tasks via the resonate-bash MCP tool. What it's good at, how to install the local Resonate server + Claude Code MCP wiring, tool reference (params, target addresses, env vars, failure semantics).

Reference:

  • resonate-defaults — Cross-SDK default values for retry policies, ctx.run options, init, env vars, and server flags. Read this when asked "what's the default for X" instead of deflecting to "check the SDK source."

Per-SDK: TypeScript

Core SDK usage:

Reasoning:

Patterns:

HTTP & authentication:

Deployments:

Per-SDK: Python

Core SDK usage:

  • resonate-basic-ephemeral-world-usage-python — Client APIs: initialization (Resonate(url=...)), registration via r.register(fn), top-level invocations (r.run/r.rpc), dependencies (r.with_dependency), external promises.
  • resonate-basic-durable-world-usage-python — Context APIs inside async def durable functions (await ctx.run/rpc/sleep/promise), determinism rules, and Python-specific deltas from TypeScript.
  • resonate-basic-debugging-python — Python-specific failure modes: async/await pitfalls, v0.7.0 SDK + Rust server v0.9.x, Python ≥ 3.12 pin, non-determinism regressions.

Patterns:

HTTP & service design:

  • resonate-http-service-design-python — FastAPI/Flask/Django route handlers that start or await durable workflows; worker-group separation; webhook-driven promise resolution.

Not yet available for Python: token-based authentication (Python SDK doesn't yet support it — planned for a future release per the docs); GCP Cloud Functions / Supabase Edge deployments (no Python shim; Supabase Edge runtime is Deno-only). Durable-sleep-scheduled-work is not a separate Python skill because ctx.sleep(timedelta(...)) is covered in basic-durable-world; a top-level r.schedule(...) cron API is available in v0.7.0 (see basic-ephemeral-world skill).

Per-SDK: Rust

SDK note: the Rust SDK is in active development (v0.6.0, published on crates.io). APIs may change between releases; every Rust skill carries this note at the top.

Core SDK usage:

  • resonate-basic-ephemeral-world-usage-rust — Client APIs: Resonate::new(ResonateConfig) / Resonate::local(), #[resonate::function] attribute macro, registration, .run() / .rpc() / .schedule(), promises API.
  • resonate-basic-durable-world-usage-rust — Context APIs inside #[resonate::function]-decorated async functions: ctx.run, ctx.rpc, ctx.sleep, .spawn() for parallelism, function kinds (Workflow / Leaf with Info / Pure leaf).
  • resonate-basic-debugging-rust — Rust-specific failure modes: serde derive errors, ctx vs info confusion, .spawn() synchronous return (use ? not .await?), tokio runtime mismatches, v0.6.0 SDK.

Patterns:

Docs-vs-source note: ctx.promise::<T>(), ctx.get_dependency::<T>(), ctx.info(), and resonate.with_dependency::<T>() all exist in the v0.6.0 SDK source but are not yet covered in docs/develop/rust.mdx. The Rust skills above use these APIs with source-path citations; docs are expected to catch up in a future release.

Not yet written for Rust: HTTP service design + deployment skills. These track SDK stability and will land when the source/docs validate the relevant paths.

Per-SDK: Go

Version note: the Go SDK's first tagged release is 0.1.0. The tag itself is 0.1.0, not v0.1.0, so Go's module proxy does not resolve @latest to it (@latest walks main and returns a newer pseudo-version instead) — install with the tag pinned explicitly: go get github.com/resonatehq/[email protected]. That resolves to the pseudo-version the proxy mints for that exact commit (confirm any install line against https://proxy.golang.org/github.com/resonatehq/resonate-sdk-go/@v/0.1.0.info before shipping it). APIs may still change before a 1.0; every Go skill carries this caveat at the top, verified against the 0.1.0 tag source and the resonatehq-examples/*-go repos.

Core SDK usage:

  • resonate-basic-ephemeral-world-usage-go — Client APIs: resonate.New(Config), the package-level generic resonate.Register, top-level RegisteredFunc.Run, Resonate.RPC / Resonate.Get, typed vs untyped handles, RunOptions, Stop semantics (don't Stop a worker), and the direct Resonate.Promises() / Resonate.Schedules() sub-clients.
  • resonate-basic-durable-world-usage-go — Context APIs inside durable functions: ctx.Run / ctx.RPC / ctx.Sleep / ctx.Promise / ctx.Detached, Future.Await, option structs, accessors, the bounded 3-attempt default retry, and the replay model.
  • resonate-basic-debugging-go — Go-specific failure modes: the localnet + NoopHeartbeat{} requirement, ctx.Run's unchecked any leaf signatures, replay double-fires, the manual-encoding trap on the low-level Sender().PromiseSettle path, and r.Stop() silently killing a live worker.

Patterns:

  • resonate-saga-pattern-go — Distributed transactions with explicit (T, error) returns, a tracked completed slice, and reverse-order compensation dispatched via type Step string + switch.
  • resonate-recursive-fan-out-pattern-go — Parallel execution via the dispatch-all-then-await-all []*resonate.Future pattern; recursive ctx.RPC self-dispatch; worker-group separation.
  • resonate-human-in-the-loop-pattern-go — Workflow steps that park on ctx.Promise() until an external actor settles, preferably via the Resonate.Promises().Resolve/Reject/Cancel sub-client (shipped in 0.1.0); the CLI and the low-level Sender().PromiseSettle remain as alternates.
  • resonate-external-system-of-record-pattern-go — Coordinate writes to an external SoR by wrapping every interaction in its own idempotent ctx.Run; idempotency keys derived from ctx.ID().
  • resonate-durable-sleep-scheduled-work-go — ctx.Sleep(time.Duration) for in-workflow durable sleep, countdowns, and long-horizon delays, plus the direct Resonate.Schedules() sub-client (create/get/delete cron schedules) shipped in 0.1.0. There is still no top-level resonate.Schedule(id, cron, fn, args) convenience wrapper like Python/TypeScript/Rust have — recurring function dispatch still composes Schedules().Create with manual resonate:target tagging, or falls back to in-workflow ctx.Sleep loops / external cron → RPC.

Not yet written for Go: HTTP service design, token-authentication, and deployment skills. The Go SDK can drive net/http services today (see example-node-drain-orchestrator-go), but the dedicated skill waits on a stable API surface; deployment skills track validated paths. 0.1.0 shipped the Promises() and Schedules() sub-clients; the remaining gap is a top-level resonate.Schedule(...) convenience wrapper that dispatches a registered function by name (Python/TypeScript/Rust have one, Go doesn't yet) — the relevant skills note the workaround rather than inventing the API.

Per-SDK: Java

Prerelease note: the Java SDK is published on Maven Central — pin io.resonatehq:resonate-sdk-java:0.1.1 (the only release; confirmed against maven-metadata.xml, not the lagging search box). The API mirrors the Python SDK and may change before a stable 1.0; every Java skill carries a light prerelease note. Requires Java 21+ (virtual threads). Every code block is compile-verified against 0.1.1 (Java 21 toolchain) and cross-checked against develop/java.mdx (docs PR #230) and the resonatehq-examples/*-java repos.

Core SDK usage:

  • resonate-basic-ephemeral-world-usage-java — Client APIs: the fluent Resonate.builder() (or new Resonate() for local mode), register via method references, top-level r.run / r.rpc / r.get, typed vs untyped handles, the promises and schedules sub-clients, per-call options, and stop semantics (don't stop a worker).
  • resonate-basic-durable-world-usage-java — Context APIs inside durable functions: ctx.run / ctx.rpc / ctx.sleep / ctx.promise / ctx.detached, ResonateFuture.await, the immutable Opts record, ctx.info accessors, type-keyed DI (ctx.getDependency), the four retry policies, and the replay model.
  • resonate-basic-debugging-java — Java-specific failure modes: the Java 21 requirement, untyped-handle Integer vs Long decoding (read through Number), CLI positional-argument arity (one parameter per --arg), the detached by-name-only constraint, rejected-promise ApplicationError handling, and r.stop() silently killing a live worker.

Patterns:

  • resonate-saga-pattern-java — Distributed transactions with a try/catch forward path, a tracked List<Step>, reverse-order compensation via an exhaustive enum + switch; retries controlled by the policy (Retry.Never) since Java has no non-retryable error wrapper. Catch Exception (await sneaky-throws).
  • resonate-recursive-fan-out-pattern-java — Parallel execution via the dispatch-all-then-await-all List<ResonateFuture<T>> pattern; recursive ctx.rpc self-dispatch to a named worker group; worker/client builder split with group(...).
  • resonate-human-in-the-loop-pattern-java — Workflow steps that park on ctx.promise() until an external actor settles. Java has an r.promises sub-client, so resolution is a clean r.promises.resolve(id, new Value(null, data)) — no manual base64 encoding needed. Go's 0.1.0 Promises().Resolve(...) sub-client now handles the same codec encoding automatically; the manual JSON → base64 → quoted string dance is only needed on Go's low-level Sender().PromiseSettle fallback path.
  • resonate-external-system-of-record-pattern-java — Coordinate writes to an external SoR by wrapping every interaction in its own idempotent ctx.run; reach the SoR client via type-keyed DI (r.withDependency / ctx.getDependency); idempotency keys from ctx.info().id().
  • resonate-durable-sleep-scheduled-work-java — ctx.sleep(Duration) for in-workflow durable sleep, countdowns, and long-horizon delays, plus the top-level r.schedule(...) cron API and the r.schedules sub-client. Java ships a top-level schedule(fn, ...) convenience wrapper; Go's 0.1.0 Schedules() sub-client covers create/get/delete but not that same one-call function-dispatch wrapper yet.

Not yet written for Java: HTTP service design, token-authentication, and deployment skills. The Java SDK supports token auth (builder().token(...)) and can sit behind HTTP route handlers today, but the dedicated skills wait on a stable API surface and validated deployment paths — mirroring the Rust/Go deferral.

Using these skills

With Claude Code

Clone this repo into your project's .claude/skills/ directory (or your user-level ~/.claude/skills/):

cd your-project
mkdir -p .claude/skills
git clone https://github.com/resonatehq/resonate-skills .claude/skills/resonate

Claude Code will automatically discover them. Invoke one explicitly with Use the resonate-saga-pattern-typescript skill to..., or let the agent pick based on the description field.

With the Anthropic SDK

Load SKILL.md files as context when you want the model to apply that skill. See Anthropic's Agent Skills docs for loading patterns.

With other agents

Skills are plain Markdown. Any agent framework that supports prompt injection or context loading can use them.

Contributing

Where does a new skill belong?

Decision tree:

  1. Is it a concept, mental model, or framework-agnostic principle that applies equally across every Resonate SDK? → Foundational. No SDK suffix. Describe the idea in language-agnostic terms and link to per-SDK skills for concrete syntax.
  2. Is it idiomatic usage of a specific SDK's API? → Per-SDK. Suffix the directory name and frontmatter name with the SDK: -typescript, -python, -rust, -go, or -java.
  3. Is it operational or deployment knowledge? → Per-SDK if the SDK shapes the deployment (e.g. Cloud Functions runtime, worker registration). Foundational if the operation is truly language-independent (e.g. installing the Resonate server binary).

Default to per-SDK. Promote a skill to foundational only when it contains no SDK-specific APIs, syntax, or runtime idioms. Debug skills, for example, are per-SDK: error codes, replay tells, and diagnostic tooling differ enough across SDKs that a single unified debug skill would either read as abstract or balloon past an agent's working context. The concept of replay and durability lives in durable-execution; the SDK-specific tells live in each SDK's debug and advanced-reasoning skills.

Same concept, multiple SDKs

When a pattern translates across SDKs (e.g. saga with compensation), each SDK gets its own skill — written idiomatically for that SDK, not find-and-replaced from another. If the natural expression differs materially (async/await vs generator syntax, Result vs exceptions), the skill reflects that. If the expressions are genuinely identical, consider whether the shared logic belongs in a foundational skill with the per-SDK skills covering only the surface syntax.

Out of scope

  • Mirroring SDK reference documentation. Skills are behaviour-oriented ("when would I reach for this?") — the per-SDK guides at docs.resonatehq.io/docs/develop/ are the reference. Skills cite them.
  • New deployment targets without SDK validation. A new deployment skill requires the target to have validated SDK support. Currently covered: GCP Cloud Functions, Supabase Edge Functions, and the Linux/systemd server install. Requests for AWS, Cloudflare, Fly, and others are tracked separately and land once an SDK and a benchmark cycle confirm the deployment path.
  • Frontmatter changes. The Anthropic Agent Skills spec (name, description, license) is fixed. Only skill content is up for discussion.

Submitting a skill

  1. Create your-skill-name[-typescript|-python|-rust|-go|-java]/SKILL.md with the frontmatter block.
  2. Keep the description specific — it's what agents use to decide when to load the skill.
  3. Put example snippets inline; put long-form references under your-skill-name/references/.
  4. Keep prose tight: skills are read by LLMs with finite context.
  5. One skill per PR unless they're tightly coupled (e.g. the TypeScript and Python variants of the same pattern).

License

Apache License 2.0. See LICENSE.