Workflows MCP Expert Skill

Activate when requests involve workflow execution, multi-step task orchestration, or CI/CD automation using the workflows-mcp MCP server.

Activation Triggers

Activate when user requests mention:

• "run workflow", "execute workflow", "list workflows"
• "orchestrate tasks", "multi-step process", "DAG execution"
• "CI/CD pipeline", "git automation", "automated testing"
• "workflow information", "workflow details"
• Task coordination with dependencies
• "Chain commands", "automate workflow"

Common user phrases: "run tests before deploying", "create build pipeline", "execute only if previous succeeds", "run tasks in parallel"

Core Workflow Pattern

Standard execution: Discover → Inspect → Execute

Always use tag-based discovery instead of guessing workflow names. Inspect workflows before execution to understand required inputs.

Step 1: Discover by Tags

Use list_workflows with tags (AND logic - workflows must have ALL tags):

Tool: list_workflows
Parameters:
  tags: ['python', 'ci']
  format: 'markdown'

Common tag combinations:

• Python: ['python'], ['python', 'testing'], ['python', 'ci']
• Git: ['git'], ['git', 'commit'], ['git', 'checkout']
• CI/CD: ['ci'], ['ci', 'deployment']
• TDD: ['tdd'], ['tdd', 'phase1']

Step 2: Inspect Workflow

Call getworkflowinfo before executing to understand inputs, outputs, and structure:

Tool: get_workflow_info
Parameters:
  workflow: 'python-ci-pipeline'
  format: 'markdown'

Step 3: Execute Workflow

Tool: execute_workflow
Parameters:
  workflow: 'python-ci-pipeline'
  inputs: {project_path: '/path/to/project'}
  response_format: 'minimal'

Response status values:

• success - Workflow completed successfully
• failure - Workflow failed (check error field)
• paused - Workflow paused for user input (use resume_workflow)

Available MCP Tools

Discovery & Information

list_workflows(tags, format) - Discover workflows by tags

• Filter with AND logic: tags=['python', 'testing']
• Returns workflow names only

getworkflowinfo(workflow, format) - Get detailed workflow metadata

• Shows inputs, outputs, blocks, dependencies
• Call before executing

Execution

executeworkflow(workflow, inputs, responseformat) - Execute registered workflow

• Provide required inputs from getworkflowinfo
• Use response_format: 'minimal' (default) or 'detailed' (debugging only)

executeinlineworkflow(workflowyaml, inputs, responseformat) - Execute YAML directly

• For one-off or custom workflows
• Validate first with validateworkflowyaml

validateworkflowyaml(yaml_content) - Validate workflow before execution

• Catches syntax errors early
• Always validate inline workflows

Checkpoint Management

resumeworkflow(checkpointid, response, response_format) - Resume paused workflow

• For interactive workflows with Prompt blocks
• Provide user response to continue

listcheckpoints(workflowname, format) - View saved checkpoints

getcheckpointinfo(checkpoint_id, format) - Inspect checkpoint details

deletecheckpoint(checkpointid) - Clean up old checkpoints

Variable Syntax Quick Reference

All variables use four-namespace architecture:

Inputs: {{inputs.project_name}}, {{inputs.workspace}}

Metadata: {{metadata.workflowname}}, {{metadata.starttime}}

Blocks: {{blocks.runtests.outputs.exitcode}}, {{blocks.test.succeeded}}

Status shortcuts (use for 90% of conditionals):

• {{blocks.test.succeeded}} - True if completed successfully
• {{blocks.build.failed}} - True if failed
• {{blocks.optional.skipped}} - True if skipped

For detailed variable syntax, load ./references/variable-syntax.md.

Essential Patterns

Conditional Execution

blocks:
  - id: run_tests
    type: Shell
    inputs:
      command: pytest tests/

  - id: deploy
    type: Shell
    inputs:
      command: ./deploy.sh
    condition: "{{blocks.run_tests.succeeded}}"
    depends_on: [run_tests]

Workflow Composition

blocks:
  - id: ci_pipeline
    type: Workflow
    inputs:
      workflow: "python-ci-pipeline"
      inputs:
        project_path: "{{inputs.workspace}}"

Parallel Execution

Blocks without dependencies run in parallel automatically.

Best Practices

1. Use tag-based discovery - Call list_workflows(tags=[...]) instead of guessing names
2. Inspect before executing - Call getworkflowinfo() to understand requirements
3. Use status shortcuts - Prefer .succeeded over .outputs.exit_code == 0
4. Minimal response format - Use response_format='minimal' unless debugging
5. Validate inline workflows - Use validateworkflowyaml() before executeinlineworkflow()
6. Explicit namespaces - Always use inputs., blocks., metadata.*

Reference Documentation

Load these files as needed using the Read tool:

Variable Syntax Reference

[./references/variable-syntax.md](./references/variable-syntax.md)

Load when: Resolving variable syntax errors, understanding namespace architecture, debugging variable resolution, or learning advanced patterns.

Contains: Complete variable resolution rules, recursive resolution, cross-block references, common mistakes, debugging techniques.

Block Executors Reference

[./references/block-executors.md](./references/block-executors.md)

Load when: Understanding available block types (Shell, Workflow, CreateFile, ReadFile, etc.), checking input/output specs, learning execution patterns, troubleshooting block issues.

Contains: Complete block type reference, input/output specifications, execution states, status vs outcome distinction, patterns and troubleshooting.

Complete Workflow Examples

[./references/examples.md](./references/examples.md)

Load when: Implementing complex multi-stage workflows, building parallel execution pipelines, creating file processing workflows, designing interactive approval workflows, learning advanced patterns.

Contains: Full workflow examples with documentation, multi-stage deployments, parallel testing with aggregation, file processing pipelines, interactive deployments.

Example Workflow Templates

Directory: ./examples/

Available templates:

• ./examples/simple-ci-pipeline.yaml - Basic CI pipeline with sequential execution
• ./examples/conditional-deploy.yaml - Environment-based deployment with conditions
• ./examples/parallel-testing.yaml - Parallel test execution with result aggregation

Usage: Copy and modify YAML templates for custom workflows. Execute using executeinlineworkflow tool.

Troubleshooting Quick Guide

Variable errors: Verify namespace (inputs., blocks., metadata.*), check block ID case-sensitivity, ensure depends_on for output references

Execution failures: Check error field, use response_format: "detailed" for debugging, verify required inputs, validate condition syntax

Workflow not found: Use list_workflows() to see available workflows, check name spelling (case-sensitive), verify MCP connection

Summary

The workflows-mcp server enables workflow orchestration through:

1. Tag-based discovery - Find workflows by purpose
2. Workflow inspection - Understand requirements before execution
3. DAG-based execution - Automatic dependency resolution and parallel execution
4. Conditional logic - Boolean shortcuts for clean conditions
5. Workflow composition - Build complex pipelines from reusable workflows

Key Pattern

Always follow: Discover → Inspect → Execute