# Writing Relayflows

Use when authoring a Relayflows flow (@relayflows/surface / @relayflows/sdk, the...

- Repository: https://github.com/AgentWorkforce/relay (1088 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add AgentWorkforce/relay --skill writing-relayflows -g -a claude-code -y`
Codex: `npx skills add AgentWorkforce/relay --skill writing-relayflows -g -a codex -y`
Cursor: `npx skills add AgentWorkforce/relay --skill writing-relayflows -g -a cursor -y`
Gemini CLI: `npx skills add AgentWorkforce/relay --skill writing-relayflows -g -a gemini-cli -y`

## Description

Use when authoring a Relayflows flow (@relayflows/surface / @relayflows/sdk, the journal-based v2 engine, the CLI is `flows`, package versions 2.0.x) in TypeScript or YAML/JSON. Covers the three-rung ladder (run/llm/agent), the resident verbs (human/dispatch/done), verification gates, TypeScript vs YAML authoring, per-step cli/model selection and its resolution order, flows.json, and `flows check`/`run`/`resume` with their real refusal shapes and exit codes. Not for the older, unrelated `@relayflows/core` WorkflowBuilder engine (`.pattern('dag')`/.agent()/.step() chains) that `writing-agent-relay-workflows` and `migrating-persona-to-relayflow` cover, that's a different product despite the similar name.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

### Overview

Relayflows turns a coding-agent task into steps a journal can inspect, verify, and resume. A flow is data (YAML/JSON) or code (TypeScript) that compiles to the same journal-backed kernel spec. Every effect is journaled before it's treated as real, a journal write that fails fails the step, with no silent fallback.

**Name collision warning.** This repo also has skills for an older, unrelated engine that is _also_ casually called "Relayflow" (singular), `@relayflows/core`'s `WorkflowBuilder`, a chained builder (`workflow('name').pattern('dag').agent(...).step(...).run()`). That's `writing-agent-relay-workflows` and `migrating-persona-to-relayflow`'s territory. This skill is the **v2** engine: `@relayflows/surface`'s `flow()` function and the YAML/JSON dialect compiled by `@relayflows/sdk`. If you see `.pattern(`, `.agent(` as a chained builder call, or `ctx.workflow.run()`, you're in the other engine, stop and use one of those skills instead.

### When to use this skill

- Writing a new `.flow.ts` or `.flow.yaml`/`.flow.json` for the `flows` CLI (package `@relayflows/sdk`, binary name `flows`).
- Deciding whether a step needs `run` (shell), `llm` (bare model call), or `agent` (harnessed coding agent in a workspace).
- Wiring up `cli`/`model` for an `agent` or `llm` step, in either language.
- Debugging a `REFUSED [...]` message from `flows check` or `flows run`.
- Choosing between TypeScript and YAML for a given flow.

### The ladder

Three step verbs, one per rung, never more (`packages/sdk/src/spec.ts`, `export type StepType = 'deterministic' | 'llm' | 'agent';`):

1. **`run` / `deterministic`**, a shell command. No model. Implicit gate is `exit_code == 0`.
2. **`llm` / `llm`**, a bare model call. Prompt in, verified output out. No workspace, no tool use.
3. **`agent` / `agent`**, a harnessed coding agent in a workspace. Returns `{ summary, artifacts }`, not raw text.

The rest: https://github.com/AgentWorkforce/relay/blob/HEAD/.agents/skills/writing-relayflows/SKILL.md