> For the complete documentation index, see [llms.txt](https://docs.pipekit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pipekit.io/ai/debug-failed-run/author-workflow.md).

# Author a Workflow

Drafting a new Argo `Workflow` from scratch is one of the higher-friction tasks in Argo. The YAML is verbose, template references are easy to mis-type, and parameter/artifact passing has its own conventions. An AI agent connected to the Pipekit MCP server can short-circuit a lot of that because the server ships authoring guidance as resources.

## How the agent authors and submits a Workflow

Given a goal (e.g. "build a DAG that fans out over a list and aggregates"), the agent:

1. Reads `pipekit://guides/workflow-authoring` for Pipekit-specific submission rules and limits.
2. Reads `pipekit://guides/parameters-and-artifacts` and `pipekit://guides/template-types` to pick the right template type and parameter passing strategy.
3. Reads `pipekit://guides/offline-lint-templateref-footgun` if the workflow references shared `WorkflowTemplates` (this guide covers the most common authoring mistake: referencing a Template that won't resolve when the workflow runs).
4. Drafts the workflow YAML.
5. Optionally calls `list_clusters` to confirm the target cluster name.
6. Calls `submit_workflow` to submit.

## Example: S3 fanout DAG to Slack

```
I want a Workflow that:
- Pulls a list of files from S3
- Fans out, one task per file
- Aggregates the per-file outputs into a single summary
- Posts the summary to Slack

Submit it to cluster `data-dev`, namespace `argo`, service account `argo-workflow`.
```

The agent drafts a `Workflow` with a DAG template, an artifact-based fanout, and a final aggregation step. It calls `submit_workflow` once it has a complete spec. You'll be prompted to confirm `submit_workflow` if your client honors MCP annotations (it's additive, not destructive, but most clients still prompt on any state change).

## Argo Workflow authoring best practices

* **Always set `namespace` and `serviceAccountName`.** The agent will ask if you don't specify them. If you can't be bothered, paste your team's defaults into the prompt. The agent will reuse them.
* **Specify `generateName`, not `name`.** This is the convention that lets [Pipe](/concepts/pipe.md) group Runs together. The authoring guide makes the same point.
* **Validate locally if you can.** Argo's `argo lint` will catch most YAML problems before submission. If your team has a local validation step, mention it in the prompt and the agent will run it before calling `submit_workflow`.

## Permission notes

`submit_workflow` is annotated `destructiveHint: false` (additive: creates a new Run, never overwrites). MCP-annotation-aware clients may still prompt before any tool that changes state. For the full list, see [Tool Inventory](/ai/tool-inventory.md).