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.
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 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, so they load only when needed.
- Things agents already do well, generic advice and restated tool documentation.
- Secrets, tokens and personal data. Use 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.
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 and Captains.