writing-agent-relay-workflows
Use when building multi-agent workflows with @relayflows/core. Covers conversation vs pipeline coordination, WorkflowBuilder/DAG steps, agents, {{steps.X.output}} chaining, repairable verification gates, evidence-based completion, mandatory Claude-then-Codex fresh-eyes review/fix loops with test hardening, channels, chat-native recipes, error handling, event listeners, step sizing, lead+workers teams, and parallel waves.
npx skills add AgentWorkforce/relay --skill writing-agent-relay-workflows --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
The skill provides concrete patterns and templates to build multi-agent workflows using @relayflows/core, including TypeScript, Python, or YAML definitions. It emphasizes choosing a coordination shape (conversation vs pipeline), setting up deterministic preflight, deterministic acceptance gates, repairable validation gates, and mandatory fresh-eyes review loops (Claude then Codex). It outlines agent roles, step definitions, verification gates, and evidence-driven repair flows, with explicit examples for both conversation and pipeline shapes and a default to conversation for non-trivial tasks. It also prescribes how to structure tests, artifacts, and deterministic checks, including how to handle blockers and commits when issues are found.
How it works
The skill instructs the agent to:
- Prefer TypeScript, then Python, then YAML for workflow definitions, and select coordination shape based on task needs.
- For each workflow, configure a preflight deterministic step and a chosen coordination pattern (conversation or pipeline).
- Implement repairable validation gates using failure capture and a repair loop, with steps that read {{steps.<gate>.output}} and rerun checks until green or blocker.
- Enforce the two mandatory fresh-eyes loops in order: Claude review/fix/final review/final fix, followed by Codex review/fix/final review/final fix.
- Require testers to add or update tests, fixtures, assertions, or proofs after fixes.
- Maintain final deterministic acceptance after the review loops and before commit/PR/handoff.
- If blocked, record BLOCKED_NO_COMMIT.md with exact evidence and skip commit.
- Provide concrete YAML/TypeScript/Python templates for steps, agents, and gates, including examples of detachable gate handling, channel management, and per-step verification rules.
When to use it
Use when building multi-agent workflows with step dependencies, coordinating different AI CLIs (claude, codex, gemini, aider, goose), creating DAG/pipeline/fan-out swarm patterns, needing verification gates and retries, and designing product-contract workflows with repair loops. Also for dynamic channel management where agents join/leave/mute mid-workflow.
What it can touch
The skill specifies interaction with tools via the relay framework and agent CLI commands (e.g., claude, codex) and includes patterns for steps, agents, and verification gates. It requires and references tooling like the @relayflows/core workflow system, and mentions explicit paths and artifacts for reviews and fixes.
Caveats
Non-negotiable checks include deterministic preflight, chosen coordination shape, repairable gates, mandatory fresh-eyes loops, and final acceptance. If a blocker remains after repairs, artifacts BLOCKED_NO_COMMIT.md should be written and commit avoided. The approach assumes availability of Claude and Codex fresh-eyes review loops and test hardening, with explicit artifact paths for review outputs.
### Overview The `@relayflows/core` workflow system orchestrates multiple AI agents (Claude, Codex, Gemini, Aider, Goose) through typed DAG-based workflows. Workflows can be written in **TypeScript** (preferred), **Python**, or **YAML**. **Language preference:** TypeScript > Python > YAML. Use TypeScript unless the project is Python-only or a simple config-driven workflow suits YAML. **Pattern selection:** Do not default to `dag` blindly. If the job needs a different swarm/workflow type, consult the `choosing-swarm-patterns` skill when available and select the pattern that best matches the coordination problem. ### When to Use - Building multi-agent workflows with step dependencies - Orchestrating different AI CLIs (claude, codex, gemini, aider, goose) - Creating DAG, pipeline, fan-out, or other swarm patterns - Needing verification gates, retries, or step output chaining - Designing product-contract workflows where failing checks should route to agents for repair instead of stopping the run - Dynamic channel management: agents joining/leaving/muting channels mid-workflow ### Non-Negotiable Workflow Checklist Every generated workflow should satisfy this checklist before it is consi
- Overview
- When to Use
- Non-Negotiable Workflow Checklist
- Default Principle: Workflows Repair Before They Fail
- Mandatory Fresh-Eyes Review Loops
- Choose Your Coordination Style — Conversation vs Pipeline
- Quick Reference (Pipeline shape)
- Quick Reference (Conversation shape)
- Default For Serious Implementation: Shadowed Squad Review Loop
- ⚡ Parallelism — Design for Speed
- Failure Prevention
- End-to-End Bug Fix Workflows
- Shipping the Result - Open a PR
- Key Concepts
BAD — sequential (14 hours for 27 workflows at ~30 min each) agent-relay node workflow run workflows/34-sst-wiring.ts agent-relay node workflow run workflows/35-env-config.ts agent-relay node workflow run workflows/36-loading-states.ts GOOD — parallel waves (3-4 hours for 27 workflows) Wave 1: independent infra (parallel) agent-relay node workflow run workflows/34-sst-wiring.ts & agent-relay node workflow run workflows/35-env-config.ts & agent-relay node workflow run workflows/36-loading-states.ts & agent-relay node workflow run workflows/37-responsive.ts &
What does the writing-agent-relay-workflows skill do?
Use when building multi-agent workflows with @relayflows/core. Covers conversation vs pipeline coordination, WorkflowBuilder/DAG steps, agents, {{steps.X.output}} chaining, repairable verification gates, evidence-based completion, mandatory Claude-then-Codex fresh-eyes review/fix loops with test hardening, channels, chat-native recipes, error handling, event listeners, step sizing, lead+workers teams, and parallel waves.
How do I install it?
Run `npx skills add AgentWorkforce/relay --skill writing-agent-relay-workflows --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From AgentWorkforce/relay, a repository with 784 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.