# Agents and setup

> Change what agents know and can use for the company, a Space, yourself or one Captain, with instructions, skills, tools, plugins and secrets.

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

Setup is what an agent loads before it starts work: instructions, skills, tools, plugins and secret names. You change it in Settings, or by asking an agent, and it takes effect on the next run. Nothing already running changes.

## Four layers

Setup comes in layers. Each layer applies to a different group of agents.

| Layer        | Where you change it                        | Who can change it            | Applies to                                                      |
| ------------ | ------------------------------------------ | ---------------------------- | --------------------------------------------------------------- |
| **Company**  | **Settings → Company → Agents**            | Company owners and admins    | Every Thread and Captain at the company.                        |
| **Personal** | **Settings → Agents**                      | You                          | Every run you start, in every Space, and your Personal Captain. |
| **Space**    | The **Agents** section of the Space's page | Space owners                 | Every Thread and Captain in that Space.                         |
| **Captain**  | The Captain's settings                     | Whoever can edit the Captain | That Captain, and the Threads it starts.                        |

Company owners and admins can also change any Shared Space's setup. Space members can read it but not change it.

A run loads the company's setup, then the sender's personal setup, then the Space's. A Captain in a Company or Shared Space loads the company's, its Space's and its own, and never anyone's personal setup. A Personal Captain loads the company's, its owner's and its own.

Choose the narrowest layer that reaches everyone who needs it. Use Personal for how you like to work, a Space for what a team shares, and the company only for what everyone needs.

## When layers disagree

- **Skills, plugins, tools, MCP servers and secrets** with the same name: the closest layer wins, with no warning. The order is Captain, then Space, then Personal, then Company.
- **Instructions** from every layer are all used, with a note that the closer layer wins if they conflict. Nothing is dropped. See [Instructions](/agents/instructions).
- **Models** follow the same idea: a Space's choice wins over a personal one. See [Models](/agents/models).

## The Agents card

The same card appears at each layer, written as a sentence you read left to right:

- **They know how to** lists skills. See [Skills](/agents/skills).
- **They can use** lists tools and connected MCP servers. See [Tools, MCP servers and connectors](/agents/tools).
- **Plus everything in** lists plugins. See [Plugins](/agents/plugins).
- **Tools can read** lists secret names. See [Secrets](/agents/secrets).

On a Captain, the same lines read **It knows how to**, **It can use** and so on.

At each line, a chip is one item and the add chip (**Add skill**, **Add tool**, **Add plugin**, **Add secret**) adds one. On a Space, items inherited from the company show in the picker as part of a group, and you cannot remove them from there.

## Setup is files

Instructions, skills, custom tools and plugins are plain files in Files, in the top folder of each layer, and Settings shows the same files. Only secrets and MCP server connections are stored apart from Files, encrypted.

```text
AGENTS.md              instructions (CAPTAIN.md in a Captain's folder)
skills/<name>/SKILL.md
tools/<name>/
plugins/<name>/
```

You can edit these files in [Files](/files), or use the command line. See [The whorl command](/reference/cli).

Secrets, a Captain's identity, Automations and sharing are not files.

## Ask an agent

Anyone can ask an agent to change setup: "Make the agent always reply in plain English", or "Add a skill for reviewing quotes." The agent has your rights and no more. If you cannot change a layer, it tells you who can.

## Check what loaded

If a file is invalid, the agent skips it. Settings shows a notice on the card when something did not load, and the next run lists what did.

## Related

- [Instructions](/agents/instructions)
- [Skills](/agents/skills)
- [Tools, MCP servers and connectors](/agents/tools)
- [Plugins](/agents/plugins)
- [Secrets](/agents/secrets)
- [Models](/agents/models)
- [Environments](/agents/environments)