Workflows

Define once, execute anywhere. Skills and multi-agent orchestration provide YAML-based automation that both humans and AI agents can run through CLI, MCP, or scheduled jobs.

Last updated:

On this page

TL;DR: Workflows in systemprompt.io combine skills, agents, and scheduled jobs into a declarative automation system. Skills define atomic capabilities in YAML. Agents execute those capabilities. Orchestrator agents coordinate multi-step processes across specialist agents. The same workflows run identically whether triggered by a human via CLI, by an AI agent via MCP, or by the scheduler on a cron expression.

The Problem

Automation in AI-powered systems typically falls into one of two traps. Either every agent is a generalist that tries to do everything (and does nothing well), or every task requires custom imperative code that is brittle and hard to maintain.

Workflows in systemprompt.io solve this by separating three concerns: what can be done (skills), who does it (agents), and when it happens (scheduling). This separation means you can compose sophisticated multi-agent processes from simple, reusable parts without writing procedural glue code.

How Workflows Work

The workflow system has four layers:

Skills define atomic capabilities. A skill is metadata describing what an agent can do, paired with detailed instructions on how to do it.
Agents are assigned skills and tools. Each agent has a system prompt, a set of skills, and access to MCP servers that provide tooling.
Orchestrators coordinate multi-agent workflows. An orchestrator receives a request, routes it to the appropriate specialist agent, and manages the overall process.
Schedulers trigger workflows on cron schedules. Jobs run in the background without human intervention.

These layers compose naturally. A skill can be shared across multiple agents. An agent can participate in multiple workflows. A workflow can be triggered manually, by another agent, or by the scheduler.

Skills: Atomic Capabilities

A skill is a reusable set of instructions that tells an AI agent how to perform a specific task. Skills are defined as YAML configuration files with accompanying Markdown content in services/skills/.

Skill Structure

Each skill lives in its own directory:

services/skills/
├── config.yaml                       # Aggregates all skill includes
├── content_writing/
│   ├── config.yaml                   # Skill metadata
│   └── index.md                      # Detailed instructions
├── workflow_designer/
│   ├── config.yaml
│   └── index.md
└── scheduler_management/
    ├── config.yaml
    └── index.md

Skill Configuration

The config.yaml defines the skill's identity and metadata:

id: content_writing
name: "Content Writing"
description: "Helps with writing, editing, and improving text content"
enabled: true
version: "1.0.0"
file: "index.md"
assigned_agents:
  - content
tags:
  - writing
  - editing
  - content
  - copywriting
  - documentation

Field	Required	Description
`id`	Yes	Unique identifier in snake_case
`name`	Yes	Human-readable display name
`description`	Yes	One-line description starting with a verb
`enabled`	Yes	Whether the skill is active
`version`	No	Semantic version for change tracking
`file`	No	Markdown file with detailed instructions
`assigned_agents`	No	Agents that use this skill by default
`tags`	No	Tags for discovery and categorization

Skill Content

The index.md file contains the detailed instructions that get loaded into an agent's context when the skill is active. This is where you define step-by-step processes, rules, guardrails, examples, and reference materials.

---
title: "Content Writing"
slug: "content-writing"
description: "Writing, editing, and improving text content."
type: "skill"
category: "writing"
---

# Content Writing

Help users write, edit, and improve text content for blogs,
documentation, and marketing materials.

## Instructions

1. Understand the audience and purpose
2. Draft content matching the requested format
3. Apply style guidelines consistently

## Rules

**Always:**
- Match the requested tone and voice
- Check for factual accuracy

**Never:**
- Fabricate quotes or statistics
- Ignore the target audience

Skill Aggregation

The root services/skills/manifest.yaml aggregates all skills through includes:

includes:
  - general_assistance/config.yaml
  - content_writing/config.yaml
  - workflow_designer/config.yaml
  - scheduler_management/config.yaml
  - analytics_monitoring/config.yaml
  # ... additional skills

skills: {}

When you add a new skill directory, add its include path here to register it with the system.

Creating a Skill

Create a skill manually or through the skill_creator guided workflow:

# Manual creation
mkdir services/skills/code_review
# Create config.yaml and index.md in the new directory
# Add include to services/skills/manifest.yaml

# Sync to database
systemprompt cloud sync local skills --direction to-db -y

# Verify
systemprompt core skills show code_review

The skill_creator skill provides a Socratic interview that walks you through purpose, examples, instructions, reference materials, categories, and voice -- then generates both files automatically.

Multi-Agent Workflows

Complex tasks often require multiple specialists working together. systemprompt.io supports this through an orchestrator pattern where a coordinating agent routes work to specialist agents.

The Orchestrator Pattern

A multi-agent workflow has three roles:

Orchestrator: Receives requests, determines routing, coordinates the overall process
Specialist agents: Handle specific steps with dedicated skills and tools
Hub agent (optional): Manages notifications and status updates across channels

This follows the "agent mesh" pattern. The orchestrator does not do the work itself -- it routes to the right specialist and manages state.

Workflow Design

The workflow_designer skill guides you through designing a workflow:

Define the trigger -- What starts the workflow? A user request, a scheduled job, or a message from another agent.
Break into steps -- Identify discrete handoff points where one agent's output becomes the next agent's input.
Map parallelism -- Determine which steps can run concurrently and which must be sequential.
Assign specialists -- Decide which agent handles each step based on required skills and tools.
Plan error handling -- Define what happens when a step fails: stop, skip, retry, or escalate.
Configure notifications -- Choose which events trigger notifications and to which channels.

Example: Blog Creation Workflow

The built-in blog creation workflow demonstrates the orchestrator pattern:

Blog Orchestrator
├── Routes to: Blog Technical    (technical articles)
├── Routes to: Blog Narrative    (narrative pieces)
├── Routes to: Blog Announcement (product announcements)
└── Reports to: systemprompt.io Hub (Discord notifications)

Each specialist has writing skills and research tools. The orchestrator's system prompt contains a routing table:

| Content Type   | Route To          | Keywords                    |
|----------------|-------------------|-----------------------------|
| Technical      | blog_technical    | architecture, code, API     |
| Narrative      | blog_narrative    | story, journey, experience  |
| Announcement   | blog_announcement | launch, release, update     |

Agent Communication

Agents communicate through the CLI message interface:

# Orchestrator sends work to a specialist (blocking, waits for response)
admin agents message blog_technical -m "Write a post about..." --blocking --timeout 300

# Specialist notifies hub on completion
admin agents message systemprompt_hub -m "WORKFLOW_COMPLETE: slug=my-new-post" --blocking

The --blocking flag makes the call synchronous, so the orchestrator waits for the specialist to finish before proceeding. The --timeout flag sets a maximum wait time in seconds.

Hub Agent and Notifications

The hub agent acts as the central nervous system for notifications. It receives status messages from the orchestrator and broadcasts them to configured channels:

Message Type	Action
`WORKFLOW_START`	Send notification that a workflow has begun
`WORKFLOW_COMPLETE`	Send notification with the result
`WORKFLOW_FAILED`	Send notification with the failure reason
`STATUS_UPDATE`	Send notification for important milestones

The hub can send notifications to Discord, log events, and store decisions in memory for future reference.

Parallel and Sequential Execution

Workflows can combine parallel and sequential steps depending on task dependencies.

Sequential Execution

Steps that depend on each other run sequentially. The orchestrator waits for each step to complete before starting the next:

Step 1: Research topic         → Agent: researcher
Step 2: Write draft (needs 1)  → Agent: writer
Step 3: Review draft (needs 2) → Agent: reviewer
Step 4: Publish (needs 3)      → Agent: publisher

Parallel Execution

Independent steps can run concurrently. The orchestrator dispatches multiple tasks and waits for all to complete:

Step 1: Research topic
  ├── Step 2a: Write summary    (parallel)
  ├── Step 2b: Generate images  (parallel)
  └── Step 2c: Draft social posts (parallel)
Step 3: Assemble final output (needs 2a, 2b, 2c)

In the orchestrator's system prompt, parallel steps are expressed as independent dispatches before a synchronization point.

Conditional Routing

Orchestrators can route based on the content of a request. The routing table in the system prompt maps request characteristics to specialist agents:

When the request involves:
- Code or architecture → route to technical_agent
- Customer stories → route to narrative_agent
- Product news → route to announcement_agent
- Unclear → route to default_agent and ask for clarification

Error Recovery and Retry

Workflows handle failures through policies defined in the orchestrator's system prompt. There are four standard approaches:

Stop on Failure

The workflow halts immediately and reports the error. Use this for critical paths where partial completion is worse than no completion.

Skip and Continue

The failed step is skipped and the workflow proceeds with the remaining steps. Use this for optional enrichment steps where the core output can still be produced.

Retry with Backoff

The orchestrator retries the failed step, typically with a modified prompt or approach. The system prompt can specify a maximum retry count:

If a specialist fails:
1. Retry once with simplified instructions
2. If still failing, notify hub with WORKFLOW_FAILED and stop

Escalate

The orchestrator notifies the hub agent and optionally a human operator. The workflow pauses until manual intervention resolves the issue.

Scheduling Integration

Workflows can be triggered automatically through the scheduler service. Jobs are defined in services/scheduler/config.yaml and use 6-field cron expressions (seconds, minutes, hours, day-of-month, month, day-of-week).

Scheduler Configuration

scheduler:
  enabled: true
  jobs:
    - name: publish_pipeline
      extension: web
      job: publish_pipeline
      schedule: "0 */15 * * * *"
      enabled: true

    - name: daily_traffic_report
      extension: web
      job: daily_traffic_report
      schedule: "0 0 7,19 * * *"
      enabled: true

    - name: analytics_aggregate
      extension: web
      job: content_analytics_aggregation
      schedule: "0 */15 * * * *"
      enabled: true

Common Schedules

Expression	Meaning
`0 /15 * * *`	Every 15 minutes
`0 0 * * * *`	Every hour
`0 0 3 * * *`	Daily at 3:00 AM
`0 0 7,19 * * *`	Twice daily at 7 AM and 7 PM
`0 0 0 * * 0`	Weekly on Sunday at midnight

Startup Jobs

Some jobs run immediately at application startup in addition to their cron schedule. The publish_pipeline job, for example, runs on startup to generate all HTML files, then continues running every 15 minutes to pick up changes.

A job runs on startup when two conditions are met:

The job implements run_on_startup() returning true in code
The job is listed in the scheduler config with enabled: true

Agent Integration

Skills are the bridge between workflows and agents. An agent's capabilities are defined by its assigned skills.

Assigning Skills to Agents

In the agent's YAML configuration, skills are listed in the card section:

card:
  skills:
    - id: "content_writing"
      name: "Content Writing"
      description: "Writing, editing, and improving text content"
      tags: ["writing", "editing", "content"]
      examples:
        - "Write a blog post about AI agents"
        - "Edit this documentation for clarity"

At runtime, the agent's system prompt includes its skill definitions. When a request arrives, the agent uses its skills to determine whether it can handle the task and how to approach it.

Skill-Gated Execution

Agents only attempt tasks that match their assigned skills. This prevents capability overreach and ensures tasks route to appropriate agents. An agent without the code_review skill will not attempt to review code, even if asked.

Skill Composition

An agent can have multiple skills. An agent with both content_writing and analytics_monitoring can handle tasks that require writing about analytics data. The combination of skills creates emergent capabilities beyond what any single skill provides.

Implementation Phases

When building a new multi-agent workflow, follow this order:

Phase 1: Skills

Create all skills needed by specialist agents. Each skill defines a specific capability with instructions, rules, and examples.

Phase 2: MCP Servers

Configure any MCP servers the agents need for tool access. Use mcp_configurator for guided setup.

Phase 3: Specialist Agents

Create each specialist agent with its assigned skills and MCP server access. Use agent_creator for guided setup.

Phase 4: Hub Agent

If the workflow needs notifications, create a hub agent configured with the appropriate channels and message formats.

Phase 5: Orchestrator Agent

Create the orchestrator last, since it needs to reference all specialist agents. Its system prompt must include the routing table, workflow steps, and error handling policy.

Phase 6: Plugin Packaging

Optionally package the complete workflow (skills, agents, MCP configs) into a distributable plugin using plugin_packager.

Configuration Reference

Item	Location	Description
Skills	`services/skills/*/config.yaml`	Skill definitions and metadata
Skill content	`services/skills/*/index.md`	Detailed instructions for agents
Skill registry	`services/skills/manifest.yaml`	Aggregates all skill includes
Agents	`services/agents/*.yaml`	Agent definitions with skill assignments
Scheduler	`services/scheduler/config.yaml`	Job scheduling configuration

CLI Reference

Command	Description
`systemprompt core skills list`	List all registered skills
`systemprompt core skills show <id>`	Show skill details
`systemprompt core skills create`	Create a new skill
`systemprompt core skills edit <id>`	Edit an existing skill
`systemprompt core skills delete <id>`	Delete a skill
`systemprompt core skills sync`	Sync skills to/from database
`systemprompt cloud sync local skills --direction to-db -y`	Push skill changes to database
`systemprompt infra jobs list`	List scheduled jobs
`systemprompt infra jobs run <name>`	Run a job immediately
`systemprompt infra jobs history`	Show job execution history
`systemprompt admin agents list`	List all agents
`systemprompt admin agents message <agent> -m "..."`	Send a message to an agent

See systemprompt core skills --help and systemprompt infra jobs --help for detailed options.

Troubleshooting

Skill not appearing in agent -- Verify the skill id in the agent YAML matches the skill config.yaml id exactly. Check that enabled: true is set in both the skill config and the agent config.

Workflow step timing out -- Increase the --timeout value in the orchestrator's message command. Complex tasks like content generation may need 300 seconds or more.

Scheduled job not running -- Check systemprompt infra jobs list to verify the job is enabled. Verify the cron expression syntax (6 fields including seconds). Check logs with systemprompt infra logs --context scheduler --level error.

Agent not responding to orchestrator -- Verify the agent is running with systemprompt admin agents list. Check that the agent's endpoint is reachable and the MCP server is connected.

Skill sync fails -- Ensure the skill's config.yaml has valid YAML and all required fields. Verify the include path exists in services/skills/manifest.yaml. Check database connectivity.

Notifications not arriving -- Verify the hub agent is running and has the correct MCP server configured. Check the Discord plugin with systemprompt plugins mcp logs marketplace. Confirm the message format matches what the hub expects (WORKFLOW_START, WORKFLOW_COMPLETE, WORKFLOW_FAILED).