> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Executor Skill

> Execute complex multi-step workflows defined in JSON or Python DSL format with conditional logic, parallel execution, and error handling.

<CardGroup cols={2}>
  <Card title="Type" icon="tag">
    `workflow_executor`
  </Card>

  <Card title="Formats" icon="code">
    JSON, Python DSL, Agent-based
  </Card>
</CardGroup>

**Purpose:** The Workflow Executor skill enables agents to run sophisticated multi-step workflows with support for conditional branching, parallel execution, and orchestration across multiple systems.

***

## Common Use Cases

<CardGroup cols={2}>
  <Card icon="rocket">
    **Multi-step deployment pipelines**

    Build, test, and deploy applications across multiple environments
  </Card>

  <Card icon="diagram-project">
    **Complex orchestration tasks**

    Coordinate operations across multiple services and systems
  </Card>

  <Card icon="link">
    **Dependent task execution**

    Execute tasks with dependencies and data passing between steps
  </Card>

  <Card icon="code-branch">
    **Conditional workflow branching**

    Make decisions based on runtime conditions and previous step outcomes
  </Card>
</CardGroup>

***

## Workflow Formats

| Format          | Best For                         | Key Features                                                            |
| --------------- | -------------------------------- | ----------------------------------------------------------------------- |
| **JSON**        | Simple, linear workflows         | Declarative syntax, version control friendly, schema validation         |
| **Python DSL**  | Complex logic, dynamic workflows | Full Python capabilities, dynamic step generation, complex conditionals |
| **Agent-based** | Multi-agent orchestration        | Delegate to specialized agents, hierarchical execution                  |

<Tip>
  **Format Selection:** Start with JSON for simple workflows, use Python DSL for complex logic, Agent-based for multi-agent coordination.
</Tip>

***

## Configuration

**Example Configuration:**

```json theme={null}
{
  "validation_enabled": true,
  "timeout": 1800,
  "allowed_executors": ["shell", "python", "docker"],
  "max_parallel_steps": 5,
  "on_failure": "stop"
}
```

<AccordionGroup>
  <Accordion title="📋 Full Configuration Reference" icon="gear">
    | Parameter                | Type    | Default              | Description                              |
    | ------------------------ | ------- | -------------------- | ---------------------------------------- |
    | `validation_enabled`     | boolean | true                 | Validate workflows before execution      |
    | `timeout`                | number  | 1800                 | Global workflow timeout (seconds)        |
    | `allowed_executors`      | array   | \["shell", "python"] | Permitted step executors                 |
    | `max_parallel_steps`     | number  | 5                    | Maximum concurrent steps                 |
    | `parallel_execution`     | boolean | true                 | Enable parallel execution                |
    | `on_failure`             | string  | "stop"               | Failure strategy (stop, continue, retry) |
    | `max_retries`            | number  | 3                    | Maximum retry attempts per step          |
    | `retry_delay`            | number  | 5                    | Delay between retries (seconds)          |
    | `enable_context_sharing` | boolean | true                 | Share data between steps                 |
  </Accordion>
</AccordionGroup>

***

## Quick Start

```bash theme={null}
# Create skill
kubiya skill create --name "CI/CD Executor" --type workflow_executor --enabled

# Associate with agent
kubiya skill associate agent <agent-id> <skill-id>
```

<Card title="View Complete Examples" icon="lightbulb" href="/core-concepts/skills/examples#cicd-pipelines">
  See full deployment pipelines, ETL workflows, and multi-agent orchestration examples
</Card>

***

## Workflow Features

### Conditional Execution

Execute steps based on runtime conditions:

```json theme={null}
{
  "id": "deploy-to-prod",
  "type": "shell",
  "command": "deploy-production.sh",
  "condition": "test_results.passed && approval.status == 'approved'"
}
```

### Parallel Execution

Run independent steps concurrently:

```json theme={null}
{
  "parallel_group": "testing",
  "steps": [
    {"id": "unit-tests", "type": "shell", "command": "npm run test:unit"},
    {"id": "integration-tests", "type": "shell", "command": "npm run test:integration"},
    {"id": "e2e-tests", "type": "shell", "command": "npm run test:e2e"}
  ]
}
```

### Data Passing Between Steps

Share outputs between workflow steps:

```json theme={null}
{
  "steps": [
    {
      "id": "get-version",
      "type": "shell",
      "command": "cat version.txt",
      "output_variable": "app_version"
    },
    {
      "id": "build-image",
      "type": "docker",
      "command": "build -t myapp:{{app_version}} .",
      "depends_on": ["get-version"]
    }
  ]
}
```

### Error Handling and Retries

Configure retry behavior for resilient workflows:

```json theme={null}
{
  "id": "api-call",
  "type": "shell",
  "command": "curl https://api.example.com/data",
  "retries": 3,
  "retry_delay": 5,
  "on_error": "continue"
}
```

***

## Example Workflow

### Deployment Pipeline

```json theme={null}
{
  "name": "deployment-pipeline",
  "steps": [
    {
      "id": "build",
      "type": "docker",
      "command": "build -t myapp:latest .",
      "timeout": 300
    },
    {
      "parallel_group": "testing",
      "depends_on": ["build"],
      "steps": [
        {"id": "unit-tests", "type": "shell", "command": "npm test"},
        {"id": "lint", "type": "shell", "command": "npm run lint"}
      ]
    },
    {
      "id": "deploy",
      "type": "shell",
      "command": "kubectl apply -f k8s/",
      "depends_on": ["testing"],
      "condition": "unit_tests.status == 'success'"
    }
  ]
}
```

***

## Security Best Practices

<AccordionGroup>
  <Accordion title="Validate Workflows" icon="shield-check">
    Always enable `validation_enabled` to catch errors before execution.

    ```json theme={null}
    "validation_enabled": true  # Validate workflow syntax and dependencies
    ```
  </Accordion>

  <Accordion title="Restrict Executors" icon="list-check">
    Limit `allowed_executors` to only necessary execution methods.

    ```json theme={null}
    "allowed_executors": ["shell", "python"]  # No docker or agent execution
    ```
  </Accordion>

  <Accordion title="Set Timeouts" icon="clock">
    Configure timeouts to prevent runaway workflows.

    ```json theme={null}
    "timeout": 1800  # Global 30-minute timeout
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  **Best Practice:** Start with `on_failure: "stop"` for production workflows to catch issues early.
</Tip>

***

## Troubleshooting & Related Skills

<AccordionGroup>
  <Accordion title="Workflow Validation Fails" icon="triangle-exclamation">
    **Solutions:**

    * Check JSON syntax is valid
    * Verify all `depends_on` references exist
    * Ensure no circular dependencies
    * Validate executor types are in `allowed_executors`
  </Accordion>

  <Accordion title="Step Timeout" icon="hourglass-end">
    **Solutions:**

    * Increase step-specific timeout
    * Increase global workflow timeout
    * Optimize step execution
    * Break into smaller steps
  </Accordion>

  <Accordion title="Context Data Not Available" icon="database">
    **Solutions:**

    * Verify `enable_context_sharing: true`
    * Check `output_variable` is set on source step
    * Ensure variable name matches in dependent step
  </Accordion>
</AccordionGroup>

### Related Skills

<CardGroup cols={2}>
  <Card title="Agent Communication" icon="users" href="/core-concepts/skills/agent-communication">
    Delegate workflow steps to specialized agents
  </Card>

  <Card title="Shell Skill" icon="terminal" href="/core-concepts/skills/shell">
    Execute shell commands in workflow steps
  </Card>

  <Card title="Docker Skill" icon="docker" href="/core-concepts/skills/docker">
    Build and deploy containers in workflows
  </Card>

  <Card title="View All Skills" icon="layer-group" href="/core-concepts/skills/built-in-skills">
    Return to built-in skills overview
  </Card>
</CardGroup>