跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
AI 与知识库

writing-relayflows

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.

AgentWorkforce · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add AgentWorkforce/relay --skill writing-relayflows

技能说明


name: writing-relayflows 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.

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.

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.

Two ways to author the same thing

TypeScript

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');
});

YAML

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

The real 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;
}

The real step shapes (YAML/JSON, packages/sdk/src/spec.ts)

```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?: numbe
阅读完整来源 ↗