Shell:B Agents

Community agent personas for Shell:B, the local-first AI workspace. Part of the family with Shell-B-Themes and Shell-B-Screensavers.

A Shell:B agent is a persona, not a program: a name and a face, a system prompt that says who it is and how it works, a model preference, a temperature and reasoning effort, and the list of tools it may use. Shell:B's built-in roster (Hephaestus, Minerva, Atlas…) is made of exactly these, and the Agent Lab edits every field live. An agent file can change how an agent behaves and which tools it reaches for, and nothing else: it runs on your models, with your approvals, inside your Shell:B.

Install one

Open the Agent Lab (the roster button in the chat composer, or /?modal=agents) and press New agent. Copy the fields from the agent's agent.json into the form: name, title, avatar, colours, description, prompt, then pick a model, set the temperature and effort, and tick its tools. Save, and it appears in the agent menu of every chat.

"model": "default" means the model you already use for chat. Anything a persona lists under needs (tools, vision, thinking) is what the model must support; most current local models with tool support will do.

One-click install from Settings, the way themes and screensavers work today, is planned; the files here already have the shape the Agent Lab saves, so nothing will need to change.

Catalogue

Agent	Role	Tools it leans on
✎ Scribe	Editor	documents, artifacts, translation
∴ Tutor	Socratic tutor	search, artifacts, multiple-choice checks, memory of your progress
⌂ Quartermaster	Household planner	search (prices and weather come with it), schedules, memory, documents
⚄ Gamemaster	Tabletop game master	real dice via the sandbox, portraits and tokens, handouts, campaign memory
✈ Navigator	Travel planner	geocoding, directions, weather, live flights, documents, reminders
❧ Chronicler	Journal and retrospectives	past conversations, memory, documents

index.json is the machine-readable version of this table.

Make one

The quickest way is to make it in Shell:B: open the Agent Lab, press New agent or Duplicate on one that is close, write the prompt, try it in a few chats, tune. When it behaves, copy the fields into an agent.json.

By hand, copy any folder under agents/ and edit. The format:

{
  "name": "Navigator",                       // 1-32 characters
  "title": "Travel planner",                 // the role shown under the name, ≤ 40
  "avatar": "✈",                             // one symbol or emoji
  "color": ["#0e7490", "#f59e0b"],           // two hex colours for the avatar gradient
  "description": "One sentence for the agent menu (≤ 200 characters)",
  "systemPrompt": "You are Navigator, a travel planner. …",   // 80 to 12,000 characters; this is the agent
  "model": "default",                        // or an Ollama tag such as "qwen3:30b"
  "needs": ["tools"],                        // what the model must support: tools, vision, thinking
  "temperature": 0.5,                        // 0 to 2
  "effort": "medium",                        // off | low | medium | high (reasoning effort)
  "tools": ["web_search", "geocode", "directions", "create_artifact"],
  "author": "Your name",
  "license": "MIT",                          // an SPDX id
  "version": "1.0",
  "tags": ["travel", "planning"]
}

Tools

scripts/tools.json lists every tool id with a one-line description, as GET /api/tools reports them. Some tools Shell:B adds by rule rather than by ticking (weather and shopping for any agent that can search, the offline wiki and law once they are installed, the Codex and library for everyone, the browser and screen in live chats): the validator warns if you list one, because it would do nothing. Two tools are reserved for the owner's orchestrator and are refused: the ones that let Shell:B change her own code.

Pick the smallest set that does the job. An agent with thirty tools spends its context reading tool descriptions and its judgement choosing between them.

Writing the prompt

The built-in agents' prompts share a few habits worth copying:

• Say who the agent is and what it is for in the first two lines. The rest is how it works.
• Describe the method, not the rules. "Ask one question, then wait for the attempt" beats "be interactive".
• Name the tools and when to use them. Models use tools they were told about, in the situations they were told.
• Be honest about actions. An agent must never say it searched, checked or computed something unless a tool call did. If the prompt says this once, in plain words, the model mostly obeys.
• Give it a way to say no. "If the draft needs a rethink rather than an edit, say so" prevents confident nonsense.
• Keep it under a screen or two. Every turn pays for every line.
• Don't put secrets, URLs, other people's names or machine-specific detail in a prompt that will be shared.

Then check it:

python3 -I scripts/validate.py

This reports errors (the Agent Lab would reject it, or a tool doesn't exist) and warnings (a tool that is added by rule, a missing version), and rebuilds index.json. See CONTRIBUTING.md for the pull request checklist. The formal schema is in agent.schema.json.

License

The scripts and this repository are MIT. Each agent names its own license in agent.json; the ones here are MIT too.