shelbi agent

View as markdown

shelbi agent <SUBCOMMAND> [OPTIONS]

shelbi agent manages the agents a project ships with: the roles (a system prompt plus an optional skill set) a workspace 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 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.

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

list

shelbi agent list

Print a table of every agent in the project: its name, the workflow statuses that reference it via the agent: field, the count of skill files under its skills/ dir, and whether its instructions.md has been customized away from the bundled default.

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

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

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

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:

shelbi agent list

Read the QA agent's instructions:

shelbi agent show qa

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

shelbi agent edit developer

Scaffold a focused reviewer:

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:

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

list

show

new

edit

Examples

See also