shelbi agent

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. Shipped agents also carry agent.yaml (which runner and model the agent uses) and a settings.json for Claude Code hooks; agent new scaffolds only instructions.md and skills/. The shared agents/_shared/preamble.md is prepended to every agent's prompt at launch time.

Shelbi writes the defaults when it creates the project. On shelbi init and shelbi reload it updates any default you haven't edited to the current release's version and leaves edited ones alone (except that runner-required orchestrator sections are appended if missing). 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, sorted by name: its name, the workflow status ids that reference it via the agent: field, the number of *.md files directly in its skills/ dir (directory-style skills such as skills/<name>/SKILL.md aren't counted), and whether its instructions.md has been customized away from the bundled default. On a fresh project:

AGENT          STATUSES                   SKILLS  CUSTOMIZED
adversarial    -                          0       no
developer      in-progress                0       no
orchestrator   backlog, todo              0       no
qa             -                          0       no
review         review                     0       no
security       -                          0       no

The CUSTOMIZED column reads:

• no: shipped default whose instructions.md still matches a bundled default (the current one, or an older release's that the next self-heal will update).
• 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 *.md file directly in skills/ with the description from its frontmatter (or (no description)). Directory-style skills (skills/<name>/SKILL.md) aren't listed, so the shipped review agent shows (none). 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 the project's agents/_shared/preamble.md (~/.shelbi/projects/<project>/agents/_shared/preamble.md in global mode, <repo>/.shelbi/agents/_shared/preamble.md in in-repo mode).

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 ASCII letters, digits, -, and _. The name doubles as the identifier referenced from workflow agent: fields, so the validator is stricter than POSIX.

edit

shelbi agent edit <NAME>

Open the agent's instructions.md in $VISUAL, falling back to $EDITOR, then vi. A blank variable is skipped, and a value with arguments (such as code -w) is split on whitespace. 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 }

See also

• Agents — what an agent is, the six shipped roles, on-disk layout, and the customization story.
• Workflows — the owner + agent fields that route a status to one of these agents.
• shelbi workspace — the slots agents run in, and the AGENT column that shows which is loaded where.