Custom Agents

Weave ships with a set of built-in agents (Loom, Tapestry, Shuttle, Pattern, Thread, Spindle, Weft, Warp). You can define entirely new ones using the same agent block syntax. There is no separate custom_agents object. Custom agents are ordinary named agent blocks in your .weave config. They participate in model resolution like any other agent, and Loom can delegate to them.

Quick Start

Add an agent block to your .weave config:

agent docs-writer {
  description "Technical documentation specialist"
  prompt "You are a technical documentation expert. Write clear, concise docs with examples. Use active voice and present tense."
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
}

That's it. Loom will now see docs-writer as a delegatable agent and can route documentation tasks to it.

Agent Block Fields

Field	Description
description	Human-readable description shown in delegation metadata
prompt	Inline system prompt text
prompt_file	Path to a .md file, resolved relative to the config scope's prompts/ directory
prompt_append	Text appended after the primary prompt source
prompt_append_file	File appended after the primary prompt source
models	Ordered model preference list (first is preferred)
mode	primary, subagent, or all. Controls selector visibility and delegation table membership
temperature	Sampling temperature (0–2)
tool_policy	Abstract capability map with allow, deny, or ask per capability
skills	Skills to inject into this agent's prompt
triggers	Delegation triggers for Loom integration

prompt and prompt_file are mutually exclusive. prompt_append and prompt_append_file are mutually exclusive.

Agent Naming Rules

Agent names must:

• Start with a lowercase letter
• Contain only lowercase letters, numbers, hyphens, and underscores
• Not collide with built-in agent names (loom, tapestry, shuttle, pattern, thread, spindle, weft, warp)

✅ docs-writer
✅ security_reviewer
✅ api-tester-v2
❌ DocsWriter       (uppercase)
❌ 2fast            (starts with number)
❌ loom             (collides with built-in)

Prompt Sources

Inline Prompt

agent api-tester {
  prompt "You are an API testing specialist. Write comprehensive test suites for REST APIs using the project's testing framework."
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
}

Prompt File

Store the prompt in a separate .md file for longer, more complex instructions:

agent api-tester {
  prompt_file "api-tester.md"
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
}

The path is resolved relative to the config scope's prompts/ directory (e.g., .weave/prompts/api-tester.md for project config).

Skills

Inject reusable skill modules into the agent's prompt:

agent api-tester {
  skills ["testing", "api-design"]
  prompt "Additional instructions specific to this agent."
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
}

Delegation Triggers

Delegation triggers tell Loom when and why to delegate to your custom agent. If you don't specify triggers, Weave generates a default based on the agent's description.

For better Loom integration, define explicit triggers:

agent docs-writer {
  description "Technical documentation specialist"
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent

  triggers [
    { domain "Documentation" trigger "README updates, API docs, user guides, changelog entries" }
    { domain "Technical Writing" trigger "Architecture decision records, design documents" }
  ]
}

These appear in Loom's delegation table, helping it route tasks accurately.

Selector Visibility

Custom agents default to mode subagent, which means:

• Loom can delegate to them
• They appear in Loom's delegation table
• They do not appear in the main selector

If you want a custom agent to be directly selectable by the user, set:

• mode primary: selector only
• mode all: selector and delegation table

Tool Policy

By default, custom agents inherit the default tool policy. Restrict access with the tool_policy block:

agent read-only-analyzer {
  prompt "Analyze code and produce reports. Never modify files."
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent

  tool_policy {
    read allow
    write deny
    execute deny
    delegate deny
    network deny
  }
}

Model Preference

Provide an ordered list of models. The adapter uses the list for fallback resolution:

agent expensive-reviewer {
  models ["anthropic/claude-opus-4", "openai/gpt-5", "google/gemini-2.0-pro"]
  mode subagent
}

Examples

Parallel Security Reviewer

Add a second security reviewer that uses a different model, giving you two independent security perspectives:

agent security-reviewer-alt {
  description "Independent security review using OpenAI"
  prompt "You are a security auditor. Review code for vulnerabilities including injection attacks, authentication flaws, data exposure, and insecure dependencies. Be thorough and skeptical."
  models ["openai/gpt-5"]
  mode subagent

  tool_policy {
    read allow
    write deny
    execute deny
    delegate deny
  }

  triggers [
    { domain "Security" trigger "Independent security review from a different model perspective" }
  ]
}

Database Migration Specialist

agent db-migrate {
  description "Database schema and migration specialist"
  prompt_file "db-migration.md"
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
  skills ["database-patterns"]

  triggers [
    { domain "Database" trigger "Schema changes, migrations, query optimization, index management" }
  ]
}

Lightweight Linter Agent

A fast, cheap agent for style checks:

agent linter {
  description "Fast code style and formatting checks"
  prompt "Check code for style issues: naming conventions, formatting, import ordering, dead code. Report issues concisely. Do not fix, only report."
  models ["anthropic/claude-haiku-4"]
  mode subagent

  tool_policy {
    read allow
    write deny
    execute deny
    delegate deny
  }

  triggers [
    { domain "Code Quality" trigger "Style checks, linting, formatting review" }
  ]
}

Custom Agents are Additive

Custom agents add to the system; they never replace built-in agents. If you want to change a built-in agent's behavior, use Agent Configuration instead.