migrating-to-workflow-sdk
Migrates Temporal, Inngest, Trigger.dev, and AWS Step Functions workflows to the Workflow SDK. Use when porting Activities, Workers, Signals, step.run(), step.waitForEvent(), Trigger.dev tasks / wait.forToken / triggerAndWait, ASL JSON state machines, Task/Choice/Wait/Parallel states, task tokens, or child workflows. For Inngest, runs the `workflow migrate inngest` codemod first and finishes what it leaves as TODOs.
How do I install this agent skill?
npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdkIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides comprehensive instructions for migrating workflow code from various platforms to the Workflow SDK. It includes some security considerations such as the processing of external code and the use of vendor-provided command-line tools. These are used within the skill's intended functionality and are well-documented within the Vercel ecosystem.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
Migrating to the Workflow SDK
Use this skill when converting an existing orchestration system to the Workflow SDK.
Intake
- Identify the source system:
- Temporal
- Inngest -> if you can run commands in the project, run
npx workflow migrate inngest --report inngest-migration.mdfirst (seereferences/inngest.md->## Start with the codemod), then migrate only what it markedTODO(workflow-migrate)and the app-boundary calls its report lists - Trigger.dev
- AWS Step Functions
- Identify the target runtime:
- Managed hosting -> keep examples focused on
start(),getRun(), hooks/webhooks, and route handlers. - Self-hosted -> also read
references/runtime-targets.mdand explicitly say the workflow/step code can stay the same, but deployment still needs aWorldimplementation and startup bootstrap.
- Managed hosting -> keep examples focused on
- Extract the source constructs:
- entrypoint
- waits / timers
- external callbacks / approvals
- retries / failure handling
- child workflows / fan-out
- progress streaming
- external side effects
Default migration rules
- Put orchestration in
"use workflow"functions. - Put side effects, SDK calls, DB calls, HTTP calls, and stream I/O in
"use step"functions. - Use
sleep()only in workflow context. - For Signals,
step.waitForEvent(), and.waitForTaskToken, choose exactly one resume surface:resume/internal->createHook()+resumeHook()when the app resumes from server-side code with a deterministic business token.resume/url/default->createWebhook()when the external system needs a generated callback URL and the default202 Acceptedresponse is fine.resume/url/manual->createWebhook({ respondWith: 'manual' })only when the prompt explicitly requires a custom response body, status, or headers.- If a callback-URL prompt does not specify response semantics, default to
resume/url/defaultand make the assumption explicit in## Open Questions.
- Never pair
createWebhook()withresumeHook(), and never passtoken:tocreateWebhook(). - Call
start()directly in the workflow for child runs, keep the returnedRun, andawait run.returnValuefor the result. CallgetRun()only inside a"use step"function. - When
step.run()-style closures become"use step"functions, pass every variable the closure read from the enclosing function as an argument. A closure that assigns to such a variable must return the new value instead. - For duplicate-start protection (Inngest
idempotency, Trigger.devidempotencyKey, Temporal workflow IDs), usestart(wf, args, { experimental_hook: { token } }). - Use
getStepMetadata().stepIdas the idempotency key for external writes. - Use
getWritable()in workflow context to obtain the stream, but interact with it (write, close) only inside"use step"functions. - Prefer rollback stacks for multi-step compensation.
- Choose app-boundary syntax in this order:
- If the prompt explicitly asks for framework-agnostic app-boundary code, use plain
Request/Responseeven when a framework like Hono is named. - Otherwise, if the target framework is named, shape app-boundary examples to that framework.
- Otherwise, keep examples framework-agnostic with
Request/Response. Do not default to Next.js-only route signatures unless Next.js is explicitly named.
- If the prompt explicitly asks for framework-agnostic app-boundary code, use plain
Fast memory aid:
- Callback URL + default ack ->
createWebhook()- Callback URL + custom ack ->
createWebhook({ respondWith: 'manual' })- Deterministic server-side resume ->
createHook()+resumeHook()
Fast-path router
Load references/resume-routing.md when the source pauses for Signals, step.waitForEvent(), or .waitForTaskToken.
Fast defaults:
- callback URL only ->
resume/url/default - callback URL + explicit custom response ->
resume/url/manual - deterministic server-side resume ->
resume/internal - self-hosted -> add
runtime/self-hosted - named framework -> add
boundary/named-framework - explicit framework-agnostic request -> add
boundary/framework-agnostic
Before drafting ## Migrated Code, write the selected route keys in ## Migration Plan.
Source references
- Temporal ->
references/temporal.md - Inngest ->
references/inngest.md - Trigger.dev ->
references/trigger-dev.md - AWS Step Functions ->
references/aws-step-functions.md
Shared references
references/shared-patterns.md: Reusable code templates for hooks, child workflows, idempotent starts, attributes, cancellation, streaming, and rollback.references/runtime-targets.md: Managed vs. customWorldguidance.references/resume-routing.md: Route-key selection, obligations, and exact## Migration Planshape.references/retries.md: Canonical retry mechanics, includingstepFn.maxRetries,RetryableError({ retryAfter }), andFatalError.
Required output shape
Return the migration in this structure:
## Migration Plan
## Source -> Target Mapping
## Migrated Code
## App Boundary / Resume Endpoints
## Verification Checklist
## Open Questions
Verification checklist
Fail the draft if any of these are true:
-
## Migration PlanomitsRoute keys -
## Migration PlanomitsWhy these route keys -
## Migration Planlists route keys that do not match the prompt -
## Migration Planlists required code obligations that do not match the selected route keys - Source-framework primitives remain in the migrated code
- Side effects remain in workflow context
-
sleep()appears inside a step - Stream interaction (
getWriter(),write(),close()) appears inside a workflow function - Child workflows wrap
start()in a step or poll for the result, instead of callingstart()in the workflow and awaitingrun.returnValue -
getRun()is called in workflow context - A lifted step closure reads a variable from the enclosing function that is not passed as an argument
- A workflow waits on the same hook token twice without disposing the first hook (the second
createHook()rejects withHookConflictError) - Two waiters share one hook token where the source delivered one event to both (give each its own token and resume each)
- A migrated Inngest signal is resumed with bare
datainstead of{ signal, data } - External writes omit idempotency keys
- Hooks/webhooks are missing where the source used signals, waitForEvent, or task tokens
- A callback-URL flow uses
createHook()+resumeHook()instead ofcreateWebhook() - A
resume/url/defaultorresume/url/manualmigration invents a user-authored callback route orresumeWebhook()wrapper whenwebhook.urlshould be the only resume surface -
createWebhook()is given a customtokenor paired withresumeHook()
Validation note:
- Reading webhook request data in workflow context is allowed. Only
request.respondWith()is step-only.
Additional fail conditions:
resume/internaloutput omitsresumeHook()in app-boundary coderesume/internaloutput omits a deterministic business tokenresume/internaloutput emitscreateWebhook()orwebhook.urlresume/url/defaultoutput does not passwebhook.urlto the external systemresume/url/defaultoutput emitsresumeHook(),respondWith: 'manual', orRequestWithResponsewithout a custom-response requirement in the promptresume/url/defaultoutput invents a user-authored callback route orresumeWebhook()wrapper whenwebhook.urlis the intended resume surfaceresume/url/manualoutput does not passwebhook.urlto the external systemresume/url/manualoutput omitsRequestWithResponseorawait request.respondWith(...)resume/url/manualoutput callsrequest.respondWith(...)outside a"use step"functionresume/url/manualoutput invents a user-authored callback route orresumeWebhook()wrapper whenwebhook.urlis the intended resume surfacecreateWebhook()is paired withresumeHook()- self-hosted output omits
World extends Queue, Streamer, Storage,startWorkflowWorld(), or the explicit note that the workflow and step code can stay the same while the app still needs a customWorld - named-framework output mixes framework syntax with plain
Request/Responseapp-boundary code without a framework-agnostic override
For concrete passing code, load:
references/shared-patterns.md->## Generated callback URL (default response)references/shared-patterns.md->## Generated callback URL (manual response)references/runtime-targets.md->## Self-hosted output blockreferences/aws-step-functions.md->## Combined recipe: callback URL on self-hosted Hono
Sample prompt
Migrate this Inngest workflow to the Workflow SDK.
It uses step.waitForEvent() with a timeout and step.realtime.publish().
Expected response shape:
## Migration Plan
## Source -> Target Mapping
## Migrated Code
## App Boundary / Resume Endpoints
## Verification Checklist
## Open Questions
Example references
Load a worked example only when the prompt needs concrete code:
references/shared-patterns.md->## Named-framework internal resume example (Hono)references/shared-patterns.md->## Generated callback URL (default response)references/shared-patterns.md->## Generated callback URL (manual response)references/runtime-targets.md->## Self-hosted output blockreferences/aws-step-functions.md->## Combined recipe: callback URL on self-hosted Hono
Reject these counterexamples:
resume/url/defaultorresume/url/manual+ user-authored callback route whenwebhook.urlis the intended resume surfacecreateWebhook()paired withresumeHook()- named-framework app-boundary output mixed with plain
Request/Responsewithout a framework-agnostic override
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/vercel/workflow/migrating-to-workflow-sdk">View migrating-to-workflow-sdk on skillZs</a>