# Instructions

> Write instructions every agent follows at your company, in a Space, for you or for one Captain, and what to put in them and what to leave out.

Source: https://docs.whorl.work/agents/instructions

Instructions tell agents how your team works, the way you would brief a new teammate. Every agent in the layer reads them on every run.

## Where to write them

Each layer has its own instructions. They sit at the top of the Agents card.

| Layer        | Where                                         | Label                                                                                                                   |
| ------------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Company      | **Settings → Company → Agents**               | **Instructions for every agent at** your company. Its placeholder reads "Tell every agent at your company how to work". |
| Personal     | **Settings → Agents**                         | **Instructions for your agents in every Space**. Its placeholder reads "Tell your agents how you like to work".         |
| Shared Space | The **Agents** section of the Space's page    | **Instructions for agents in** the Space. Its placeholder reads "Tell agents how to work in this Space".                |
| Captain      | **Captain settings**, from the Captain's menu | The Captain's own instructions. They define who the Captain is and how it works.                                        |

Type the instructions and choose **Save changes**. You can only edit a layer you are allowed to change. See [Agents and setup](/agents/setup).

The instructions are stored in a file named AGENTS.md at the top of the layer's folder in Files. A Captain's are in a file named CAPTAIN.md in its folder, under Captains. You can edit the files in [Files](/files) instead.

## How layers combine

Whorl joins the instructions from every layer that reaches an agent, in this order: company, personal, Space, Captain. Each is labelled with its layer. One line above them says that the closer layer wins if two disagree. Nothing is dropped.

## What belongs in instructions

- **Facts the agent cannot discover** and needs on most runs: who the team is, the names of key systems, where things live, house style.
- **Rules that always apply**, each with its reason. "Send customer email from the shared mailbox, because replies must reach the whole team."
- **A pointer to a skill** for each procedure. "To price a quote, use the pricing-review skill."

## What does not

- **Step-by-step procedures.** Put them in a [skill](/agents/skills), so they load only when needed.
- **Things agents already do well**, generic advice and restated tool documentation.
- **Secrets, tokens and personal data.** Use [secrets](/agents/secrets).

## Style

- Write short, direct sentences, one rule per bullet.
- Explain why, instead of using capitals or words like "CRITICAL". Plain rules are followed reliably. Shouted rules get over-applied.
- Prefer one concrete example to a list of edge cases.
- Keep each layer under about 100 lines. Every line costs the agent attention on every run, so when the instructions grow, move procedures into skills.

## Captain instructions

A Captain's instructions open with who it is and what it is for.

```markdown
You are the pricing desk for Acme's sales team. You answer quote questions, check discounts
against the pricing policy and draft quotes for a salesperson to send.

- Use the pricing-review skill for every quote.
- Never send a quote yourself; a salesperson sends it after review.
```

A Captain's model does not come from this file. It comes from the model settings. See [Models](/agents/models) and [Captains](/captains).

## Related

- [Agents and setup](/agents/setup)
- [Skills](/agents/skills)