- name
SKILL.md
技能檔案保留在發布者的儲存庫中。
在終端機中貼上複製的指令。它會將這個 SKILL.md 安裝到對應的代理中。
npx skills add AgentWorkforce/relay --skill writing-relayflows -a cursor -y在終端機中貼上複製的指令。它會將這個 SKILL.md 安裝到對應的代理中。
npx skills add AgentWorkforce/relay --skill writing-relayflows -a claude-code -y在終端機中貼上複製的指令。它會將這個 SKILL.md 安裝到對應的代理中。
npx skills add AgentWorkforce/relay --skill writing-relayflows -a codex -y在終端機中貼上複製的指令。它會將這個 SKILL.md 安裝到對應的代理中。
npx skills add AgentWorkforce/relay --skill writing-relayflows -a grok -y在 Grok Bot 聊天中傳送複製的訊息。Bot 會從 GitHub 取得這個 SKILL.md,並加入你所有 Bot 共用的技能中。
Install this skill: https://github.com/AgentWorkforce/relay/tree/HEAD/.agents/skills/writing-relayflows來自發布者
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.
.flow.ts or .flow.yaml/.flow.json for the flows CLI (package @relayflows/sdk, binary name flows).run (shell), llm (bare model call), or agent (harnessed coding agent in a workspace).cli/model for an agent or llm step, in either language.REFUSED [...] message from flows check or flows run.Three step verbs, one per rung — never more (packages/sdk/src/spec.ts, export type StepType = 'deterministic' | 'llm' | 'agent';):
run / deterministic — a shell command. No model. Implicit gate is exit_code == 0.llm / llm — a bare model call. Prompt in, verified output out. No workspace, no tool use.agent / agent — a harnessed coding agent in a workspace. Returns { summary, artifacts }, not raw text.Plus four resident verbs that aren't ladder rungs: human (durable approval), dispatch (hand off to a child flow), done (typed finish), and in YAML, on/triggers (event entry points — out of scope for this skill).
Most flows only need run and llm. Climb to agent once a step needs hands on a real workspace.
import { flow } from '@relayflows/surface';
export default flow('hello', async (f) => {
const greeting = await f.run('echo "Hello from Relayflows"');
console.log(greeting.trim());
const answer = await f.agent('greeter', {
task: 'Reply with one short hello sentence. Do not use tools or modify files.',
cli: 'claude',
model: 'claude-sonnet-4-6',
});
console.log(answer.summary);
f.done('success');
});
version: '0.1.0'
name: hello
steps:
- id: greeting
type: deterministic
command: 'echo "Hello from Relayflows"'
- id: greeter
type: agent
dependsOn: [greeting]
instruction: 'Reply with one short hello sentence. Do not use tools or modify files.'
cli: claude
model: claude-sonnet-4-6
Ctx contract (TypeScript)packages/surface/src/context.ts, current as of origin/main@86a2ec2:export interface AgentResult {
summary: string;
artifacts: string[];
}
export interface AgentOptions {
task: string;
workspace?: string;
cli?: string;
model?: string;
}
export interface Ctx {
run(command: string): Step<string>;
llm(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;
llm(
prompt: string,
options: { output: Record<string, unknown>; cli?: string; model?: string }
): Step<unknown>;
agent(name: string, options: AgentOptions): Step<AgentResult>;
human(question: string, options: { to: string }): Promise<boolean>;
dispatch<T>(flow: string, input: unknown): Promise<T>;
done(reason: RunCompletionReason): void;
cloud: CloudHelper;
slack: SlackHelper;
}
packages/sdk/src/spec.ts)interface DeterministicStepSpec {
type: 'deterministic';
id: string;
command: string;
dependsOn?: string[];
timeoutMs?: number;
verification?: VerificationSpec; // omit for implicit exit_code
}
interface LlmStepSpec {
type: 'llm';
id: string;
prompt: string;
dependsOn?: string[];
verification?: OutputVerificationSpec;
model?: string;
cli?: string;
}
interface AgentStepSpec {
type: 'agent';
id: string;
instruction: string;
dependsOn?: string[];
verification?: OutputVerificationSpec;
agent?: string; // selects a named FlowSpec.agents entry
cli?: string;
model?: string;
surfaces?: { workspace?: { surface: string }[]; streams?: { stream: string }[]; external?: string[] };
recoveryMode?: 'reset' | 'inspect' | 'manual'; // default 'reset'
permissions?: {
fileGlobs?: string[];
networkAllowlist?: string[];
accessPreset?: 'readonly' | 'readwrite';
};
}
interface FlowSpec {
version: string; // required, e.g. '0.1.0' — not optional
name?: string;
cli?: string; // flow-level CLI default
agents?: Record<string, { cli: string; model: string }>; // both fields required
steps: StepSpec[];
budget?: { maxTokensIn?: number; maxTokensOut?: number; maxDollars?: string };
}
packages/sdk/src/spec.ts, VerificationGateType):- id: classify
type: llm
prompt: 'Classify this ticket as bug, feature, or question: "the export button does nothing"'
cli: claude
model: claude-sonnet-4-6
verification:
type: output_contains
value: bug
cli / model: what a step actually runs oncli and model directly (TypeScript since flows#310, AgentOptions.cli?/.model?). Resolution order for cli — checked once per step by preflight.ts's resolveCli (packages/sdk/src/preflight.ts:265-282), identical regardless of authoring language because both compile to the same StepSpec:$ flows check hello.flow.yaml # agent step, no cli anywhere
REFUSED [cli_unresolved] Step "greeter" has no CLI at step, flow, or project level. No flows.json was found from "..." to the filesystem root.
flows.json{ "cli": "claude", "executors": ["cron"], "models": ["claude-sonnet-4-6"] }
import { flow } from '@relayflows/surface';
export default flow('ship-feature', async (f) => {
const plan = await f.agent('planner', {
task: 'Research and plan: add OAuth2 support',
workspace: 'acme/api: readonly', // compiles to relayauth path scopes
});
const ok = await f.human(`Ship this?\n${plan.summary}`, { to: 'khaliq' });
if (!ok) return f.done('canceled');
const pr = await f.dispatch('garden/implement', plan); // hands off to a child flow
f.done('success');
});
flows check / run / resumepackages/sdk/src/cli.ts):flows check [--json] <flow.yaml|spec.json>
flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <flow.yaml|spec.json>
flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <flow.ts> --input <inline-json-or-file>
flows resume [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] <run-id>
version in a YAML/JSON FlowSpec. It's required, not optional — flows check refuses a spec without it.agents: to a TypeScript flow() header. FlowHeader has no such field; it throws TypeError: flow header has unknown fields: agents at authoring time. Named-agent maps + agent: selector are YAML/JSON-only (flows#300 tracks TypeScript composition via use:, not yet shipped).flows.json's models sets a default model. It only validates models already declared elsewhere; it never selects one..then()-chaining one. Both are refused (unawaited_step / unsupported_verb) rather than silently ignored — the executor closes every root operation's lifecycle explicitly..flow.ts without --input. Required even for flows that don't use their input argument.done() reason. The set is closed: success | step_failed | canceled | budget_exceeded. Don't invent partial or skipped.agents: { reviewer: { cli, model } } + reuse across steps by name) — YAML/JSON only today. Tracked for TS composition via use: at flows#300.recoveryMode, permissions, surfaces, budget, memory on agent steps — real YAML/JSON fields with no TypeScript equivalent. Author that step in YAML and reach it from TypeScript with f.dispatch if you need them.flows run --cloud), triggers/webhooks, memory retrieval, and the f.mcp/f.slack helper namespaces — each is its own surface with its own gotchas; see the Relayflows product docs for what's shipped versus designed-but-not-yet-implemented.@relayflows/core WorkflowBuilder engine — see writing-agent-relay-workflows and migrating-persona-to-relayflow in this repo.AgentWorkforce/flows@86a2ec2 (origin/main). Built packages/surface and packages/sdk from source in a clean worktree (published npm @relayflows/[email protected] is stale — it predates flows#310 and lacks cli/model on AgentOptions; local build was symlinked in instead), then ran the real CLI:$ flows check hello.flow.yaml # this skill's YAML example, cli/model added, flows.json models allowlist set
CHECK PASSED hello.flow.yaml # exit 0
$ flows check hello.flow.ts # this skill's TypeScript example
CHECK PASSED hello.flow.ts # exit 0
$ flows check extract.flow.yaml # this skill's output_contains example
CHECK PASSED extract.flow.yaml # exit 0
$ flows check hello.flow.yaml # same YAML, no flows.json anywhere
REFUSED [cli_unresolved] Step "greeter" has no CLI at step, flow, or project level. ... # exit 2
$ flows check hello.flow.yaml # step model not in flows.json's models[]
REFUSED [model_unknown] Step "greeter" declares model "claude-sonnet-4-6" ... not listed in project model registry ... # exit 2
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
---name: writing-relayflowsdescription: Use when authoring a Relayflows flow (@relayflows/surface / @relayflows/sdk, the journal-based v2 engine — the…---# .agents/skills/writing-relayflows/SKILL.md總覽
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.
常見問題
從發布者下載 .agents/skills/writing-relayflows/SKILL.md,或複製路徑後開啟儲存庫。PlugMCP 只收錄這項技能,不代管檔案。
發布者將它存放在 https://github.com/AgentWorkforce/relay。
Claude、Cursor、Codex 和 Grok Build 可以讀取你從發布者儲存庫加入的 SKILL.md。在聊天中傳送技能的 GitHub 資料夾連結,Grok Bot 就會安裝它。