write-delegate-agent

An agent file is a role this server can run: frontmatter that sets the dispatch, and a body that instructs the model. delegate_to_agent and delegate_to_agent_readonly take its name.

This file is itself a valid agent file in the format it describes, so it doubles as the worked example.

Where the file goes

Three locations, first match wins, so a project's own agent shadows a personal one of the same name:

1. <project>/.claude/agents/<name>.md
2. <project>/.claude/skills/<name>/SKILL.md
3. <agents_dir>/<name>.md — the personal tier, set by DELEGATE_AGENTS_DIR

The filename supplies the name — <name>.md, or the skill directory for a SKILL.md. A name must match ^[A-Za-z0-9_-]+$: it is a name, not a path, so it cannot traverse.

Frontmatter

---
name: test-writer
description: Writes and extends pytest tests for a changed module.
model: deepseek-v4-flash
effort: low
max_turns: 20
max_tokens: 32768
keep_tool_results: 6
allowed_tools: [read_file, write_file, run_bash]
network: false
---

You write tests for existing code. Read the module, then write tests that would have
caught the bug described in the task. Run them. Iterate until they pass.

Report the outcome of the final test run.

A frontmatter block is required — a --- line, a closing ---, and something between them: a file with no block, or whose --- lines are adjacent, is refused. No individual field is required, so a block of one blank line yields an all-default agent.

Every key must be one of these ten. An unknown key is refused, not ignored, because a typo that costs you a setting in silence is the failure this format was rewritten to prevent:

Key	Value	Notes
name	the agent's name	Optional, but if present it must equal the filename, or the file is refused — and a bare name: counts as present, because a key whose value went missing is a setting that silently does nothing
description	one line	What list_agents reports, so a caller can choose without opening the file
model	a model-registry key	Binds the dispatch
effort	off, low, high, max	Refused loudly if misspelt. Not medium — the backend has no such level. Not inherit — that is what a caller passes to defer to this file
max_turns	integer ≥ 1	Above the server's hard cap the file is refused, not clamped: a caller's number is transient, a file is committed and trusted
max_tokens	integer ≥ 1	Reply budget; the model's own cap still applies afterwards
keep_tool_results	integer ≥ 0	How many recent tool results survive history eviction. 0 evicts each one as the next turn starts
allowed_tools	[a, b]	From read_file, search_files, read_git, run_bash, write_file, edit_file. Naming an unimplemented tool is refused. Brackets are the format: bare a, b is refused, and so is a - block list
network	true / false	Default false. An operator grant: the agent must also be listed in DELEGATE_AGENT_NETWORK_ALLOWED and found in the personal tier
extra_binds	[a, b]	Extra directories visible in the sandbox, within operator-set roots. Read-only, and the denylist still reaches inside. Bracketed like allowed_tools, and refused the same way