# shelbi agent

Manage the project's agents — the roles (system prompt + skills) a workspace runs. List them, print one's instructions, scaffold a new one, or open one in your editor.

```text
shelbi agent <SUBCOMMAND> [OPTIONS]
```

`shelbi agent` manages the [agents](/docs/concepts/agents) a project ships
with: the roles (a system prompt plus an optional skill set) a
[workspace](/docs/concepts/workspaces) loads when it picks up a task. Every
project starts with six (`orchestrator`, `developer`, `review`, `qa`,
`security`, `adversarial`), and these subcommands surface them and let you
author more.

Agents live under the project's `agents/` directory:
`~/.shelbi/projects/<project>/agents/<name>/` in the default
[global mode](/docs/concepts/config-modes) or
`<repo>/.shelbi/agents/<name>/` in in-repo mode. Each has an
`instructions.md` (its prompt) and an optional `skills/` directory. The
shared `agents/_shared/preamble.md` is prepended to every agent's prompt at
launch time. The defaults are seeded on first load and never clobbered on
upgrade. See [customizing an agent](/docs/concepts/agents#customizing-an-agent).

Every subcommand accepts the global `-p / --project <PROJECT>` flag, omitted
from the per-subcommand tables below.

## list

```text
shelbi agent list
```

Print a table of every agent in the project: its name, the workflow
statuses that reference it via the
[`agent:` field](/docs/guides/getting-started/workflows#owners-and-agents), the count of
skill files under its `skills/` dir, and whether its `instructions.md`
has been customized away from the bundled default.

```text
AGENT          STATUSES                   SKILLS  CUSTOMIZED
orchestrator   -                          0       no
developer      InProgress, Todo           0       no
review         Review                     1       no
qa             -                          0       no
security       -                          0       no
adversarial    -                          0       no
```

The `CUSTOMIZED` column reads:

- `no` — shipped default whose `instructions.md` matches the bundled body
  byte-for-byte.
- `yes` — shipped default that's been edited (or whose file is missing on
  disk and would re-materialize on the next `shelbi reload`).
- `-` — an agent you authored; there's no bundled body to compare against.

## show

```text
shelbi agent show <NAME>
```

Print the agent's `instructions.md` to stdout, followed by a `Skills:`
section listing each `skills/*.md` file with the `description` from its
frontmatter. Errors if the agent doesn't exist.

This shows you what *one* agent's file holds in isolation. It does **not**
prepend `agents/_shared/preamble.md`. That composition happens at launch
time, not at `show` time. To see the shared preamble, `cat
~/.shelbi/projects/<name>/agents/_shared/preamble.md`.

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `<NAME>` | string | — | Agent name (positional, required). |

## new

```text
shelbi agent new <NAME>
```

Scaffold a new agent directory under `agents/<NAME>/` with a starter
`instructions.md` and an empty `skills/`. The starter prompt is a minimal
role template, not a copy of `developer`. It's there to be replaced.

Errors if an agent with that name already exists. Names must be non-empty,
must not start with `.` or `_`, and may only contain `a-z`, `0-9`, `-`, `_`.
The name doubles as the identifier referenced from workflow `agent:`
fields, so the validator is stricter than POSIX.

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `<NAME>` | string | — | Agent name (positional, required). |

## edit

```text
shelbi agent edit <NAME>
```

Open the agent's `instructions.md` in `$EDITOR` (falling back to `$VISUAL`,
then `vim`). Errors if the agent doesn't exist. Run `shelbi agent new
<NAME>` first, or `shelbi reload` to materialize the shipped defaults if
this is the first time the project's been opened.

Edits take effect the next time the affected agent is launched: for the
orchestrator, on the next `shelbi reload`; for a workspace agent, on its
next task dispatch.

## Examples

See the project's agents and where each is used:

```bash
shelbi agent list
```

Read the QA agent's instructions:

```bash
shelbi agent show qa
```

Bake your repo's conventions into the default developer agent:

```bash
shelbi agent edit developer
```

Scaffold a focused reviewer:

```bash
shelbi agent new perf-review
shelbi agent edit perf-review
```

Then wire it into a workflow status. Reference the status by `id` (its
`name` and `category` live in `statuses.yaml`) and name the agent:

```yaml
statuses:
  - { id: perf, owner: agent, agent: perf-review }
```

## See also

- [Agents](/docs/concepts/agents) — what an agent is, the six shipped
  roles, on-disk layout, and the customization story.
- [Workflows](/docs/guides/getting-started/workflows#owners-and-agents) — the `owner` +
  `agent` fields that route a status to one of these agents.
- [`shelbi workspace`](/docs/cli/workspace) — the slots agents run in, and
  the `AGENT` column that shows which is loaded where.