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

# Use workflows

> Use Mintlify workflows to automate recurring docs maintenance: choose the right trigger, write effective instructions, and get consistent agent results.

Workflows run the agent automatically so your content stays accurate without manual effort. This guide covers how to choose the right workflow, configure it effectively, and write instructions that produce consistent results.

## When to use workflows

Workflows are best for tasks that are:

* **Repetitive**: The same task runs regularly on a predictable schedule or whenever a specific event occurs.
* **Time-consuming**: Tasks that take time to do manually but follow a consistent pattern.
* **Reactive**: Tasks that should happen automatically in response to code or content changes, like updating docs after a feature ships.

For one-off or exploratory tasks, use the agent directly in the [dashboard](https://app.mintlify.com) or from Slack.

## Choose a trigger

Each workflow runs on one of three trigger types. Choose the one that matches when you need the work done.

| Trigger         | Use when                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Content update  | The task should run whenever your project content changes—translating new pages, fixing broken links, or auditing SEO metadata. |
| Code change     | The task should run when source code changes—updating API specifications or documentation after a PR merges.                    |
| Custom schedule | The task should run on a fixed cadence regardless—publishing weekly changelogs or running periodic grammar checks.              |

## Predefined workflows

Mintlify includes predefined workflows for the most common content maintenance tasks. Toggle any of them on from the [Workflows](https://app.mintlify.com/products/workflows?tab=workflows) page of your dashboard.

See [Predefined workflows](/workflows/reference) for more details.

## Custom workflows

Create a custom workflow for tasks that aren't covered by the predefined options. Custom workflows give you full control over the trigger, instructions, and context repositories.

See [Create a custom workflow](/workflows/create) for setup steps.

### Write effective instructions

Custom workflow instructions are prompts the agent follows on every run. The quality of your instructions directly affects the consistency of results.

**Describe the outcome, not just the task.** Tell the agent what done looks like.

<CodeGroup>
  ```text Less effective theme={null}
  Review the API reference pages.
  ```

  ```text More effective theme={null}
  Review every page in the /api-reference directory. For each endpoint, confirm that the request parameters, response fields, and example payloads match the OpenAPI spec in the api/openapi.yaml file. Open a pull request with corrections for any discrepancies you find.
  ```
</CodeGroup>

**Write a procedure.** Agents follow step-by-step instructions more reliably than open-ended prompts.

```text Example procedure theme={null}
1. Read the merged pull request diff from the trigger repository.
2. Identify any changed API endpoints, parameters, or response shapes.
3. Search the documentation for pages that reference those endpoints.
4. Update the affected pages to match the changes in the pull request.
5. Open a pull request with a summary of the pages you changed and why.
```

**Keep scope narrow.** A workflow that does one thing well is more reliable than one that tries to do many things. Split complex tasks across multiple workflows.

**Specify files and directories.** The more precise you are about where the agent should look, the less time it spends searching.

```text Example with specific paths theme={null}
Check every MDX file in the /content directory for broken internal links (links beginning with /). 
For each broken link, either fix the path or remove the link if no replacement exists.
```

### Use context repositories

For custom workflows and some predefined workflows, you can add context repositories the agent reads when the workflow runs.

Add context repositories when:

* Your content references code, APIs, or configuration that lives in a separate repository.
* You want the agent to compare your content against source code when deciding what to update.
* The workflow prompt refers to files outside your Mintlify project repository.

You can add up to 10 context repositories per workflow.

### Update mode

Decide how much review you want before changes go live.

* **Automatic**: Changes merge directly into your Mintlify project repository without review. Best for low-risk, high-frequency tasks like translation, grammar checks, and link fixes.
* **Require review**: The agent opens a pull request and a human reviews it before merging. Best for tasks that change content meaning, like syncing with code changes or updating API references.

## Control credit usage

Every workflow run consumes credits. For example, most **update from code changes** workflow runs cost between 40 and 180 credits. Complex runs that update many pages cost more.

Scheduling cron jobs to run at specific times gives you more precise control over credit usage. For example, run a workflow once a day or once a week to know exactly how many pull requests it creates per month. Push-triggered workflows can vary more from month to month because they depend on how often content or code changes.

## Review and improve workflow results

Workflows run automatically, but they benefit from periodic review.

1. Open the **Runs** tab on the [Workflows](https://app.mintlify.com/products/workflows) page to see recent run history and status.
2. Click a run to read the agent's summary and review any pull requests it opened.
3. If results are inconsistent, refine your instructions: add more specific procedures, narrow the file scope, or split the workflow into smaller tasks.

A few review cycles after enabling a new workflow are usually enough to dial in the instructions.


## Related topics

- [Workflows overview](/docs/workflows/index.md)
- [Guides](/docs/guides/index.md)
- [How to maintain documentation over time](/docs/guides/maintenance.md)