boocode/data/skills/anthropics/developing-agents/SKILL.md

name, description

name	description
developing-agents	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)

## 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):

## 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:

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.