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

# Creating a Workflow

> Learn how to create a workflow in TeamCopilot, what files it includes, and how to turn a repeatable operational task into runnable automation.

A workflow is the right choice when you want TeamCopilot to run a repeatable task as code.

In TeamCopilot, workflows are created through the AI Assistant, then refined in the workflow editor.

## Before you create one

Create a workflow when:

* the task should run the same way every time
* you need Python code to execute the task
* the task needs structured inputs
* the task interacts with APIs, files, or external systems

If the task mainly needs instructions for the AI, create a skill instead.

## How to create a workflow

1. Open TeamCopilot.
2. Go to the **AI Assistant**.
3. Ask the assistant to create a workflow for a specific task.
4. Be clear about the workflow's purpose, inputs, and expected output.
5. After the assistant creates it, open it from the **Workflows** tab.
6. Review and edit the generated files.
7. Declare any required secret keys and configuration.
8. Have an engineer approve the workflow before running it in production.

From the product UI today, workflows are created by talking to the AI Assistant. Once created, they appear in the Workflows section where you can inspect, edit, approve, and run them.

```mermaid theme={null}
flowchart LR
    A[Create workflow] --> B[Review workflow.json]
    B --> C[Implement run.py]
    C --> D[Install dependencies]
    D --> E[Declare required secrets]
    E --> F[Engineer approves snapshot]
    F --> G[Run manually, via chat, API, or cronjob]
```

## What gets created

Each workflow lives in:

```text theme={null}
workflows/<slug>/
```

A workflow is a small package of files. The core files are:

```text theme={null}
workflows/<slug>/
├── workflow.json
├── README.md
├── run.py
├── requirements.txt
├── .venv/
└── requirements.lock.txt
```

Depending on how the workflow was generated, you may also see extra support files such as `.env` or `.env.example`. For secrets, prefer TeamCopilot secret management rather than storing raw values in those files.

## What each file does

* `workflow.json`: defines the workflow contract, including its intent, inputs, and runtime timeout
* `README.md`: documents what the workflow does and how it should be used
* `run.py`: contains the executable Python logic
* `requirements.txt`: lists Python dependencies
* `.venv/`: contains the workflow's isolated Python environment
* `requirements.lock.txt`: records the exact installed dependency versions

## The most important file: `workflow.json`

`workflow.json` defines how TeamCopilot understands the workflow.

It includes:

* `intent_summary`: a human-readable description of the workflow
* `inputs`: the parameters the workflow accepts
* `required_secrets`: the secret keys TeamCopilot must resolve before the workflow can run
* `triggers.manual`: whether it can be run manually
* `runtime.timeout_seconds`: how long it can run before timing out

This file powers both the workflow contract and the manual run UI.

The current contract is Python-based and file-system backed. If you change the execution model later, update this page first so the docs stay aligned with the actual workflow runtime.

## Writing `run.py`

`run.py` should implement one clear task end to end.

In practice, that means:

* parse inputs
* perform the workflow logic
* print useful output
* fail clearly if something goes wrong

Keep the workflow focused. If the script starts doing several unrelated jobs, it is usually time to split it into separate workflows.

## Adding dependencies and secrets

When a workflow needs external packages:

* add them to `requirements.txt`
* install them into the workflow's local virtual environment
* refresh `requirements.lock.txt`

When a workflow needs credentials:

* declare the key names in `workflow.json` under `required_secrets`
* have the user add those keys in **Profile Secrets**, or ask an engineer to provide a **Global Secret**
* read the values in `run.py` from environment variables such as `os.environ["STRIPE_SECRET_KEY"]`

Example:

```json theme={null}
{
  "intent_summary": "Create a Stripe customer",
  "required_secrets": ["STRIPE_SECRET_KEY"]
}
```

```python theme={null}
import os

stripe_key = os.environ["STRIPE_SECRET_KEY"]
```

TeamCopilot blocks runs when a required secret is missing and tells the user which key to add in **Profile Secrets**.

Do not put raw secrets in `workflow.json`, `README.md`, chat instructions, or source comments.

## Reviewing and testing a workflow

Before asking your team to use a workflow:

* check that the slug and intent still match what it does
* confirm the inputs are clear and correctly typed
* verify the timeout is reasonable
* document required setup in `README.md`
* test it with realistic inputs
* get engineer approval

After approval, users can run the workflow from TeamCopilot, including through the manual run UI for workflows with defined inputs.

## How workflows are used after creation

Workflows can be started from several places:

* the manual run screen
* chat prompts
* cronjobs
* workflow API keys

That means a good workflow should have a clear contract, strong input validation, and a focused `run.py` entrypoint.

## When to choose a workflow instead of a skill

Choose a workflow when the main value is reliable execution.

Examples:

* syncing data between systems
* generating a report
* provisioning a standard resource
* running an operational remediation step

If the main value is guidance, process, or reasoning, create a skill instead.