---
title: Tasks
description: What the agent has to do — written once, run many ways.
---

A task is two things: the instructions, and the files that belong to them. It is
deliberately separable from an experiment, because the same instructions given to
a different agent is the entire point.

## Writing one

You can write a task in either place:

- **New experiment** — the composer on the left. Type the instructions and press
  **Add task**; it is saved to your library and ticked for this launch. The
  chevron beside the button offers *Add to tasks only*, for when you are just
  stocking the library.
- **Tasks** — the *New task* dialog, with a name field and a file picker.

Leave the name blank and the first line of the instructions becomes it, trimmed
to fit a list.

## What makes a good task

Write it the way you would brief a new engineer, not as a prompt.

```text title="A task"
The checkout spec is flaky. Find out why and fix it.
Prove it by running the spec twenty times without a failure.
```

Two things to include, and one to leave out:

1. **Say what done looks like**

    An agent that cannot tell whether it has succeeded will stop at the first
    plausible-looking moment. "Prove it by running the spec twenty times" is the
    difference between a fix and a claim.

2. **Name the files by the name they will have**

    An uploaded file lands in the working directory under its own name and a
    repository lands in a directory named after it, so the task can say "read
    `orders.csv`" or "the bug is in `billing-api/`" and the agent will find it.

3. **Do not prescribe the tools**

    How an agent gets there is exactly what the experiment exists to compare.
    Telling all of them to use ripgrep flattens the thing you were measuring.

## What is not on a task

The **machine** and the **rubric** are chosen when you launch, not here. That is
what lets one task be run three different ways — on a bigger box, against a
stricter standard — without being rewritten or duplicated.

## Files on a task

Attach a file to the task when it is part of what the task *means*. A run
receives the task's files and the experiment's files, merged and de-duplicated:
the same repository picked in both places is one clone, not two.

See [Files and repositories](/build/files).

## Reusing and removing

The Tasks table shows, per task, which files it carries, how many experiments
have used it, and how many runs it has produced.

A task that has produced runs **cannot be deleted** — deleting it would orphan
them, and the refusal says so. Delete the experiment instead, which takes its
runs with it. A task with no runs deletes cleanly.