workflow-building

Workflow Building

This skill teaches you how to create workflow templates — YAML-based definitions of multi-step processes that are executed as a DAG (Directed Acyclic Graph) of tasks. Each step is assigned to a team member by role and runs automatically with dependency tracking.

When to Use Workflows

Workflows are for repeatable, multi-step processes where:

• Multiple agents need to collaborate in a defined sequence
• Steps have clear dependencies (B waits for A to finish)
• The same process runs repeatedly with different parameters
• You want automatic scheduling (daily, weekly, etc.)

Do NOT use workflows for: one-off tasks, simple single-agent work, or ad-hoc coordination.

How to Create Workflows

There are two ways to create a workflow, depending on context:

For an existing (live) team

Use the workflow_create tool:

workflow_create(name: "content-publishing", yaml: "<full YAML content>")

This writes the YAML file directly to ~/.markus/teams/{teamId}/workflows/.

For a team package (builder artifact)

Write the YAML file via file_write to the team's artifact directory, then reference it in team.json:

file_write("~/.markus/builder-artifacts/teams/{team-name}/workflows/my-workflow.yaml", "<YAML content>")

In team.json, add:

{
  "team": {
    "members": [...],
    "workflows": ["workflows/my-workflow.yaml"]
  }
}

The workflow YAML files are copied to ~/.markus/teams/{teamId}/workflows/ when the team is installed.

YAML Format Reference

Top-Level Fields

name: content-publishing           # REQUIRED. Identifier (kebab-case, English)
displayName: Content Publishing    # Optional. Human-readable name (any language)
description: Research, write, ...  # REQUIRED. What this workflow does
version: "1.0.0"                   # REQUIRED. Semver

schedule:                          # Optional. Auto-trigger configuration
  every: "1d"                      #   Interval shorthand: 30m, 6h, 1d, 1w
  cron: "0 9 * * 1-5"             #   OR cron expression
  run_at: "2025-06-01T09:00:00Z"  #   OR one-shot ISO timestamp
  timezone: "Asia/Shanghai"        #   IANA timezone (default: server local)
  max_runs: 10                     #   Stop after N runs (0 = unlimited)

params:                            # Optional. User-provided or auto-generated inputs
  - name: topic                    #   Referenced as {{topic}} in step prompts
    type: string                   #   string | enum | text | agent
    label: "Content Topic"
    required: true
  - name: platform
    type: enum
    options: ["wechat", "zhihu", "xiaohongshu", "x.com"]
    default: "wechat"

steps:                             # REQUIRED. The task DAG (at least one step)
  - id: research
    name: Research Topic
    type: agent_task
    role: researcher
    prompt: "Research {{topic}} thoroughly and produce a summary."
    priority: high