v1.20Grok Build CLI support →

Workflows

A workflow is a WORKFLOW.md file with frontmatter that declares the model, tools, MCP servers, and secrets for a repeatable multi-agent pipeline.

Why workflows exist

An ad-hoc agents run prompt works for one-offs. A workflow encodes the contract for a task that runs repeatedly — code review, changelog drafting, triage — so the same configuration runs consistently every time. The frontmatter is the spec; the body is the orchestrator system prompt.

Workflows are distinct from teams. A team runs agents in parallel across independent surfaces. A workflow is a sequential pipeline contract where one orchestrator decides which subagents to spawn and in what order.

The WORKFLOW.md frontmatter

---
name: Code Review
description: Evidence-grounded review of a PR or pending changes.
model: claude-opus-4-7
tools:
  - Read
  - Grep
  - Bash
mcpServers:
  - github
  - linear
allowedAgents:
  - security-reviewer
  - test-writer
secrets:
  - github.com
  - linear.app
---

You are Code Reviewer for this repo...

Secrets bundles listed in secrets: are injected from macOS Keychain at run time. Pass --no-auto-secrets to skip injection. See secrets for how bundles are created.

Run a workflow

# Default mode is plan — read-only, no file writes:
agents run code-review "review PR #42"

# For workflows that write files or call APIs:
agents run code-review --mode full "review PR #42 and post the comment"

The workflow name replaces the agent argument. If the workflow writes files and you leave mode at the default (plan), it will deadlock at ExitPlanMode.

Install and manage

agents workflows list                             # table with sync status
agents workflows view code-review                 # model, tools, MCP, subagents, secrets
agents workflows add gh:user/workflows            # install from GitHub
agents workflows add ./code-review                # install from a local directory
agents workflows remove code-review               # remove from version homes

Workflows resolve project-first: .agents/workflows/ > ~/.agents/workflows/ > ~/.agents-system/workflows/. A project-scoped workflow with the same name as a user-scoped one wins.

Related