Skip to content

SPECIALISTS.md

Latest commit

 

History

History
140 lines (105 loc) · 4.22 KB

SPECIALISTS.md

File metadata and controls

140 lines (105 loc) · 4.22 KB
Raw

Zero Specialists

Specialists are named sub-agents that Zero can delegate focused work to through the Task tool. A specialist is a markdown manifest with YAML-style frontmatter plus a system prompt body.

Specialists can be built in, user-scoped, or project-scoped:

Scope Path Notes
Built-in compiled into Zero worker, explorer, and code-review ship with the binary.
User ~/.config/zero/specialists/*.md Available across local workspaces.
Project .zero/specialists/*.md Shared with the current repository when committed.

Project specialists override user and built-in specialists with the same name. User specialists override built-ins.

CLI Management

zero specialist list
zero specialist show worker
zero specialist path

zero specialist create api-review \
  --project \
  --description "Reviews API changes" \
  --tools read-only,plan \
  --prompt "Review API changes for compatibility and missing tests."

zero specialist edit api-review --project
zero specialist delete api-review --project

Use --json with list, show, path, create, or delete when scripting. create --force replaces an existing manifest, but refuses symlink overwrites. edit also refuses symlink manifests before opening $VISUAL or $EDITOR.

Manifest Format

---
name: api-review
description: Reviews API changes for compatibility and missing tests.
tools:
  - read-only
  - plan
---

Review API changes for behavior regressions, compatibility breaks, and missing
tests. Report concrete findings with file paths.

Supported frontmatter keys:

Key Purpose
name Lowercase specialist id. Use letters, numbers, and dashes.
description Short summary shown in listings and task metadata.
extends Optional base specialist to inherit prompt/model/tools from.
model Optional model override. Empty means inherit the parent model.
reasoningEffort Optional reasoning effort override.
tools Array of tool categories or tool ids.

If the body is empty and description is set, Zero uses the description as the system prompt and reports a warning in zero specialist show.

Tool Selection

Known categories:

Category Tools
read-only read_file, list_directory, grep, glob
edit read-only tools plus write_file, edit_file, apply_patch
execute read-only tools plus bash
plan update_plan

Specialist manifests cannot enable Task, TaskOutput, TaskStop, or GenerateSpecialist, so child specialists cannot spawn more specialists or author new ones.

Agent Tools

Zero registers these tools for top-level agent runs:

Tool Purpose
Task Launch a specialist sub-agent for a focused prompt.
TaskOutput Read or block on a background specialist task's output.
TaskStop Stop a running background specialist task.
GenerateSpecialist Create a project-local specialist manifest from a description.

GenerateSpecialist is project-scoped only. It writes to .zero/specialists, not the user specialist directory.

Example LLM-facing Task payload:

{
  "name": "explorer",
  "description": "Find session storage code",
  "prompt": "Find the files that create, load, and list sessions."
}

Background task payload:

{
  "name": "worker",
  "description": "Audit release docs",
  "prompt": "Check the release docs for stale TypeScript references.",
  "run_in_background": true
}

The returned task_id is also the child session id. Use it with TaskOutput, TaskStop, or Task resume.

Background State

Background specialist output is stored under:

${XDG_DATA_HOME:-~/.local/share}/zero/background/

Each task has:

  • <task_id>.ndjson for the child process stream output
  • <task_id>.json for task metadata such as status, PID, parent session, and timestamps

Persisted metadata lets a new background manager instance read completed task output or stop a still-running task by id.

If Zero is restarted while a background task is still marked running, the new manager marks that task error and clears its PID. This avoids sending TaskStop to a stale PID that may now belong to an unrelated process.