---
name: developing-agents
description: Propose new agents for BooCode's data/AGENTS.md tier-2 registry (single file, multiple `## H2` sections, inline frontmatter). Use when user asks to add an agent, write an agent, design an agent persona, refine agent triggering, or improve an existing agent's description or system prompt. Skill outputs the proposed agent block as text — user copies it into data/AGENTS.md manually.
---

# Agent Development (BooCode tier-2 format)

> BooChat adaptation: this skill is a heavy rewrite of the upstream Anthropic `agent-development` skill. The upstream targets Claude Code's per-file `agents/<name>.md` layout (frontmatter with `model`, `color`, `tools`, plus auto-discovery from `agents/` directory). BooCode uses a **single combined file** at `data/AGENTS.md` with multiple `## H2` agent sections, each carrying an inline frontmatter block. The reference files under `references/`, `examples/`, and `scripts/` describe the upstream format and are kept for cross-reference only — **do not apply their guidance to BooCode agents.**

## Quick overview

A BooCode agent is one `## H2` section inside `data/AGENTS.md`. Each section contains:

1. An H2 title (the human-readable agent name, e.g. `## Debugger`)
2. An inline frontmatter block (`---` … `---`) with three fields
3. A system-prompt body in markdown

The agent is resolved per-turn by `sessions.agent_id`. Multiple agents live in the same file; ordering is by appearance.

## Canonical example (from data/AGENTS.md)

```markdown
## Debugger
---
temperature: 0.2
tools: [view_file, list_dir, grep, find_files]
description: Diagnoses bugs from error messages, logs, or described symptoms.
---
You diagnose bugs. Form a hypothesis, prove it with evidence from the code.

Process:
1. Restate the symptom in one line. Confirm you understand it.
2. Read the error/stacktrace. Identify the exact frame where things go wrong.
3. view_file on that frame. Read 50 lines around it.
4. grep for callers, related state, recent changes that could explain it.
5. State the root cause with file:line evidence.
6. Propose the minimal fix. Note any side effects.

Rules:
- Never guess. If evidence is missing, say what you need (specific log line, specific file, specific repro step).
- Distinguish symptom from cause. A null check fixes the symptom; missing init causes it.
- Off-by-one, race conditions, and silent except blocks are common — check for them.
- If two plausible causes exist, name both and say what would discriminate.

Output:
- Symptom: <one line>
- Root cause: <file:line> — <explanation>
- Fix: <minimal diff or description>
- Risk: <what could break>
```

### Second example — agent with a constrained tool list (illustrative)

The Debugger gets the full default read-only set. A more locked-down agent narrows further. Example (synthetic — not in `data/AGENTS.md` today; included to show how the `tools` whitelist is used in practice):

```markdown
## View-only Auditor
---
temperature: 0.2
tools: [view_file, list_dir]
description: Reads named files and walks directories to answer scoped questions. Does not search. Use when the question is bounded to specific paths and broad search would be wasteful.
---
You read what you're pointed at. You do not search.

Process:
1. Confirm the user named specific files or a specific directory. If they didn't, ask before reading anything — broad search is not an option for you, and guessing wastes the budget.
2. view_file each named path. Cap at 3 files per question unless the user expands scope.
3. list_dir to confirm structure if the user is asking about layout.
4. Answer with file:line citations.

Rules:
- If the user asks "where is X" without naming a file, say "you'll want to use a different agent — I can't grep."
- Don't infer a path; ask for it.

Output:
- Answer: <prose>
- Evidence: file:line citations only
```

The difference from the Debugger is the `tools` array: dropping `grep` and `find_files` forces the agent to either work from the user's explicit pointers or hand off. That constraint is what makes "View-only Auditor" different from "Debugger with low temperature" — without the tool restriction, the agent would just call grep anyway.

There are 6 builtin agents in `data/AGENTS.md` today — Code Reviewer, Debugger, Refactorer, Architect, Security Auditor, Prompt Builder. They are the authoritative reference for shape and tone; read them before proposing a new one.

## Frontmatter fields

Exactly three fields are honored. Anything else is silently ignored (forward-compat hook, not a feature).

### `temperature` (number, 0.0–2.0)

LLM sampling temperature for this agent. Lower = more deterministic. Common settings observed in the builtin agents:

| Temp | Use case |
|---|---|
| 0.2 | Diagnostic / security work where evidence > creativity |
| 0.3 | Reviews, refactors (specific, narrow output) |
| 0.4 | Prompt builders (some variation; still grounded) |
| 0.5 | Architects / designers (broader exploration) |

Match the tone you want. Don't copy a number without understanding why.

### `tools` (array of tool-name strings)

The allowlist of tools the agent may call. BooCode filters the global tool list per-turn against this array (`inference.ts:721-731`). Unknown names in the array are silently dropped.

Current canonical tool names in BooCode (as of v1.13.x):

`view_file`, `list_dir`, `grep`, `find_files`, `git_status`, `skill_find`, `skill_use`, `skill_resource`, `ask_user_input`, `web_search`, `web_fetch`

Read-only set commonly given to investigation agents: `[view_file, list_dir, grep, find_files]`. Add `git_status` if branch state matters. Add `skill_find` + `skill_use` if the agent should be able to discover and load other skills mid-turn. `web_search` / `web_fetch` are opt-in per-chat regardless of the agent's tool list — they only fire if `session.web_search_enabled` (or the project default) is true.

**Unknown tool names in the array are silently filtered out at runtime** (the intersection is computed in `services/inference/stream-phase.ts:403–406` and there's no warning log for the dropped names). Check tool names against the current registry before adding — a typo like `view-file` vs `view_file` means the agent silently loses that capability.

**No `model` field.** Session model wins per the locked v1.8.2 decision; an agent inherits whatever model the chat is set to.

### `description` (string, prose)

The trigger summary. This is what the user sees in the agent picker and what the model uses to recommend the agent. Keep it under one short paragraph. The format that works:

```
<What the agent does in one sentence>. <One or two short trigger phrases>.
```

Examples from the canonical 6:

- *"Reviews code for bugs, security issues, and maintainability. Read-only."*
- *"Diagnoses bugs from error messages, logs, or described symptoms."*
- *"Designs new features, modules, or architectural changes. Outputs a build plan."*

Patterns that work in the description:
- Verb-first ("Reviews", "Diagnoses", "Audits") — the agent is doing something
- "Read-only" or similar capability hints when the agent is constrained
- A noun phrase saying what's produced ("outputs a build plan", "outputs plans, not edits")

Patterns to avoid:
- "Helps the user with X" (vague; says nothing)
- Lists of features ("Reviews, audits, suggests, refactors, and improves...") — pick the dominant verb
- "Use when..." prose (the trigger sentence is implicit in the verb-first description)

## System prompt body

The body becomes the agent's system prompt, appended after the base prompt and the container guidance block. Write in second person ("You diagnose…", "You design…"). Aim for ~150–400 words. Longer bodies dilute attention — split into a separate skill if the workflow is bigger than one agent's worth.

### Shape that has been working

Most builtin agents use this skeleton:

```markdown
You are <role>. <One-line stance on quality / output discipline>.

Process:
1. <Verb> <noun> — <why>
2. <Verb> <noun> — <why>
...

Rules:
- <Imperative>
- <Imperative — often "never X" or "always Y">

Output:
- <Field>: <one-line shape>
- <Field>: <one-line shape>
```

Variants observed:
- `Prioritize:` / `Reject:` paired lists (Refactorer)
- `Look for:` long bulleted catalog (Security Auditor)
- `Skip:` to explicitly disclaim non-goals (Code Reviewer)

### Discipline

- **Be specific about what the agent doesn't do.** Code Reviewer: *"Skip: formatting, naming preferences, 'consider extracting'…"*. Saying what you reject sharpens the description's positive claim.
- **Cite the BooCode tooling.** Mention `view_file`, `grep`, etc. by name in the process steps. The model is more likely to actually use them when the prompt names them.
- **No second system-prompt.** The base prompt already covers "be concise, cite file:line." Don't restate it.
- **No emojis.** None of the builtin agents use them; the convention is plain text.

## How to propose a new agent

1. Identify the gap. Is there a recurring kind of task that the current 6 don't cover well? If a builtin can be tweaked, prefer tweaking.
2. Pick a verb-first name. Title-case, two words max (Debugger, Code Reviewer).
3. Write the description in one or two sentences.
4. Pick a temperature deliberately (see table above).
5. List the minimum tools needed.
6. Draft the system prompt: stance, process, rules, output.
7. Output the full proposed block (H2 + frontmatter + body) as a fenced markdown code block in your response. Don't mkdir, don't write — Sam pastes it into `data/AGENTS.md` and commits.

## Common mistakes

- **Adding a `model` field** — silently ignored; the session model wins.
- **Adding a `color` field** — silently ignored.
- **Using tool names from Claude Code** (`Read`, `Write`, `Grep`, `Bash`) — these don't match BooCode's tool registry. Use the BooCode names from the list above.
- **Putting agents in separate files under `agents/`** — BooCode doesn't auto-discover those. Everything lives in `data/AGENTS.md`.
- **Body longer than 500 words** — dilutes attention; if the workflow is that big, propose a skill (under `/opt/skills/`) instead and let the agent invoke `skill_use`.

## What this skill outputs

For each agent proposal: one fenced markdown block ready to paste into `data/AGENTS.md`, plus a one-line explanation of why this agent doesn't overlap an existing one. Nothing else.
