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

Step Fields

Parameter Types

Built-in Template Variables

These are available in all step prompts without declaring params:

• {{date}} — Current date (YYYY-MM-DD)
• {{time}} — Current date and time (YYYY-MM-DD HH:MM)
• {{run_number}} — Sequential run number for this workflow

Upstream Inputs

When a step depends on another step's output, use inputs to create a named reference:

steps:
  - id: research
    name: Research
    type: agent_task
    role: researcher
    prompt: "Research {{topic}} and produce a summary document."

  - id: write
    name: Write Draft
    type: agent_task
    role: writer
    depends_on: [research]
    inputs:
      - from: research       # Step ID of the upstream step
        as: research_notes    # Variable name in this step's context
    prompt: "Write a draft about {{topic}} using the upstream research."

The system automatically injects context about upstream deliverables into the step's prompt. The downstream agent can use task_get to retrieve the upstream step's full deliverables.

DAG Design Patterns

Linear Chain

Steps run one after another. Simple and predictable.

# A → B → C
steps:
  - id: research
    name: Research
    type: agent_task
    role: researcher
    prompt: "Research the topic."

  - id: write
    name: Write
    type: agent_task
    role: writer
    depends_on: [research]
    prompt: "Write based on research."

  - id: review
    name: Review
    type: agent_task
    role: editor
    depends_on: [write]
    prompt: "Review and finalize the draft."

Fan-Out (Parallel)

Multiple independent steps run simultaneously after a shared predecessor.

#        ┌→ write_cn
# plan ──┤
#        └→ write_en
steps:
  - id: plan
    name: Plan Content
    type: agent_task
    role: editor
    prompt: "Create content outline for {{topic}}."

  - id: write_cn
    name: Write Chinese Version
    type: agent_task
    role: chinese_writer
    depends_on: [plan]
    inputs: [{ from: plan, as: outline }]
    prompt: "Write the Chinese version based on the outline."

  - id: write_en
    name: Write English Version
    type: agent_task
    role: english_writer
    depends_on: [plan]
    inputs: [{ from: plan, as: outline }]
    prompt: "Write the English version based on the outline."

Fan-In (Aggregation)

One step waits for multiple parallel steps to complete.

#  write_cn ──┐
#             ├→ publish
#  write_en ──┘
steps:
  # ... (plan, write_cn, write_en as above)

  - id: publish
    name: Final Review & Publish
    type: agent_task
    role: editor
    depends_on: [write_cn, write_en]
    inputs:
      - { from: write_cn, as: chinese_draft }
      - { from: write_en, as: english_draft }
    prompt: "Review both drafts and prepare for publishing."

Diamond

Combination of fan-out and fan-in — a common pattern for parallel work with consolidation.

#        ┌→ B ──┐
#  A ────┤      ├→ D
#        └→ C ──┘

Role Design

Roles are placeholders that get mapped to actual team members at run time. The system auto-resolves roles by matching role names to agent names, skills, or role types.

Best practices:

• Use descriptive role names that match your team composition: editor, chinese_writer, researcher, reviewer
• Each role should map to a distinct team member or function
• The reviewer field defaults to the team manager — only override if a specific specialist should review
• Keep role names consistent across workflows in the same team

Schedule Configuration

Interval-Based

schedule:
  every: "6h"        # Run every 6 hours
  timezone: "Asia/Shanghai"

Supported units: s (seconds), m (minutes), h (hours), d (days), w (weeks).

Cron-Based

schedule:
  cron: "0 9 * * 1-5"   # Weekdays at 9am
  timezone: "Asia/Shanghai"

Standard 5-field cron: minute, hour, day-of-month, month, day-of-week.

One-Shot

schedule:
  run_at: "2025-07-01T09:00:00+08:00"

Fires once at the specified time, then stops.

Complete Examples

Example 1: Content Publishing Pipeline

A 4-step pipeline for a content team: plan → parallel writing → review.

name: content-publishing
displayName: Content Publishing Pipeline
description: Plan content, write in parallel across platforms, then review and publish
version: "1.0.0"

params:
  - name: topic
    type: string
    label: Content Topic
    required: true
    description: The main topic or theme for this content batch
  - name: target_platforms
    type: text
    label: Target Platforms
    default: "WeChat, Xiaohongshu, X.com"

steps:
  - id: plan
    name: Content Planning
    type: agent_task
    role: editor
    priority: high
    prompt: |
      Create a detailed content plan for: {{topic}}
      Target platforms: {{target_platforms}}

      Produce:
      1. Content angle and key messages
      2. Platform-specific adaptation notes
      3. Target audience for each platform
      4. SEO keywords / hashtags

  - id: write_chinese
    name: Write Chinese Content
    type: agent_task
    role: chinese_writer
    depends_on: [plan]
    inputs: [{ from: plan, as: content_plan }]
    prompt: |
      Write Chinese content about {{topic}} following the content plan.
      Produce drafts for WeChat public account and Zhihu.

  - id: write_xhs
    name: Write Xiaohongshu Notes
    type: agent_task
    role: xhs_operator
    depends_on: [plan]
    inputs: [{ from: plan, as: content_plan }]
    prompt: |
      Create Xiaohongshu notes about {{topic}} following the content plan.
      Produce 2-3 note drafts with title, body, hashtags, and image descriptions.

  - id: review_and_publish
    name: Editorial Review
    type: agent_task
    role: editor
    depends_on: [write_chinese, write_xhs]
    inputs:
      - { from: write_chinese, as: chinese_drafts }
      - { from: write_xhs, as: xhs_drafts }
    prompt: |
      Review all content drafts for {{topic}}.
      Check for consistency, quality, and brand voice alignment.
      Provide final approval or revision notes for each piece.

Example 2: Research Report

A linear pipeline: research → analyze → write report.

name: research-report
displayName: Research & Report
description: Deep research on a topic, data analysis, and formatted report
version: "1.0.0"

params:
  - name: research_question
    type: text
    label: Research Question
    required: true
  - name: depth
    type: enum
    options: ["brief", "standard", "deep-dive"]
    default: "standard"

steps:
  - id: research
    name: Gather Sources
    type: agent_task
    role: researcher
    priority: high
    timeout: "2h"
    prompt: |
      Research: {{research_question}}
      Depth level: {{depth}}

      Gather information from multiple sources. Save key findings,
      data points, and source references as deliverables.

  - id: analyze
    name: Analyze Findings
    type: agent_task
    role: analyst
    depends_on: [research]
    inputs: [{ from: research, as: raw_findings }]
    prompt: |
      Analyze the research findings for: {{research_question}}
      Identify patterns, insights, and actionable conclusions.
      Produce a structured analysis document.

  - id: report
    name: Write Final Report
    type: agent_task
    role: writer
    depends_on: [analyze]
    inputs: [{ from: analyze, as: analysis }]
    prompt: |
      Write a comprehensive report on: {{research_question}}
      Use the analysis to structure the report with:
      - Executive summary
      - Key findings
      - Detailed analysis
      - Recommendations
      Format as a polished HTML deliverable.

Example 3: Scheduled Daily Digest

An automatically triggered daily workflow.

name: daily-digest
displayName: Daily Content Digest
description: Automatically gather and summarize daily updates
version: "1.0.0"

schedule:
  cron: "0 9 * * 1-5"
  timezone: "Asia/Shanghai"

steps:
  - id: gather
    name: Gather Updates
    type: agent_task
    role: researcher
    prompt: |
      Gather today's updates and news for {{date}}.
      Check industry trends, competitor activity, and team progress.

  - id: summarize
    name: Write Daily Summary
    type: agent_task
    role: writer
    depends_on: [gather]
    inputs: [{ from: gather, as: updates }]
    prompt: |
      Write a concise daily digest for {{date}} (run #{{run_number}}).
      Summarize the key updates and highlight action items.

Validation Rules

The system validates your YAML before saving. Common errors:

• Missing required fields: name, description, version, and at least one step
• Each step requires: id, name, role, prompt
• Duplicate step IDs: every id must be unique
• Invalid depends_on references: must reference existing step IDs
• Circular dependencies: the DAG must be acyclic (A→B→C→A is invalid)
• Enum params without options: type: enum requires a non-empty options[]
• Invalid schedule: must have at least one of every, cron, or run_at

Rules

• Keep workflows focused: each workflow should serve one clear purpose. Don't combine unrelated processes.
• Role names must match team composition: roles are resolved to team members. Use names that correspond to the team's actual member names or skills.
• Write clear prompts: each step's prompt should be self-contained enough for the assigned agent to execute without ambiguity. Include expected outputs.
• Use depends_on for ALL dependencies: if step B needs output from step A, it MUST list A in depends_on. Without this, steps run in parallel.
• Use inputs for deliverable passing: when a downstream step needs to reference upstream output, declare it in inputs so the system injects the context.
• Test incrementally: start with 2-3 steps and validate before adding complexity.
• The name field MUST be English kebab-case (e.g., content-publishing, daily-report).