Agent Builder

Agent Builder

Create a new sub-agent from user requirements. Produces a YAML config file + prompt file under ~/.flocks/plugins/agents/<name>/, loadable by the system without restart.

Required directory layout:

~/.flocks/plugins/agents/
└── {name}/          ← subdirectory named after the agent (kebab-case)
    ├── agent.yaml   ← YAML config
    └── prompt.md    ← system prompt

⚠️ Do NOT create flat files like agents/{name}.yaml — the subdirectory format is mandatory.

Workflow

1. Clarify Requirements

Use the Question tool to confirm (skip if already clear):

• Agent name: kebab-case format (e.g. threat-analyst, code-reviewer)
• Role description: one-sentence summary of the agent's specialty
• Capability boundary: what the agent can and cannot do
• Execution mode: read-only analysis (read_only) / general execution (react) / plan-then-execute (plan_and_execute) / codebase exploration (explore)

2. Generate Prompt File

Create ~/.flocks/plugins/agents/{name}/prompt.md with the following structure:

You are a specialized {role} agent.

## Mission
{Core responsibilities, 1-2 paragraphs}

## Capabilities
- **Capability 1**: specific description
- **Capability 2**: specific description

## Output Format
{Structured output requirements: tables, checklists, etc.}

## Constraints
- {Constraint 1}
- {Constraint 2}

Prompt writing principles:

• Open with a clear role identity
• List concrete capabilities, not vague descriptions
• Define a structured output format so callers can use results directly
• Constraints must be consistent with the declared tools allowlist (e.g. a read-only agent should not claim it can edit files)

3. Generate YAML Config File

Create ~/.flocks/plugins/agents/{name}/agent.yaml. Prefer an explicit tools allowlist; use permission only for advanced wildcard matching or deny/allow patterns that cannot be expressed as a simple list.

# Required
name: {name}                    # kebab-case, globally unique
description: >                  # One-sentence description; Rex uses this to decide when to delegate
  {Agent's role and specialty}

# Behavior
mode: subagent                  # Always "subagent" for sub-agents
strategy: read_only             # react | plan_and_execute | read_only | explore
delegatable: true               # Whether delegate_task can invoke this agent
hidden: false                   # Whether to hide from the frontend

# Prompt source (pick one)
prompt_file: prompt.md          # External prompt.md in the same directory (recommended)
# prompt: "inline prompt..."    # Inline (for short prompts)
# prompt_builder: "module:func" # Dynamic Python builder (advanced)

# Optional
color: "#E74C3C"                # Frontend display color, 6-digit hex
temperature: 0.3                # 0.0 - 1.0
# top_p: null
# steps: 50                    # Max execution steps

# Model override (optional; omit to use the global default)
# model:
#   provider_id: custom-openai-compatible
#   model_id: "claude-sonnet-4-5-20250929"

# Preferred tool allowlist
tools:
  - read                        # Open as needed
  - grep
  - glob
  # - bash                      # When shell execution is needed
  # - edit                      # Covers write/edit/apply_patch-style file mutations
  # - websearch                 # When web search is needed
  # - webfetch                  # When web fetching is needed
  # - delegate_task             # When re-delegation is needed (use with caution)

# Advanced / legacy alternative when wildcard rules are really needed
# permission:
#   "*": deny
#   read: allow
#   grep: allow
#   glob: allow

# Delegation metadata (tells Rex when to delegate to this agent)
prompt_metadata:
  category: {domain}            # Domain category, e.g. security / code-quality / devops
  cost: medium                  # CHEAP / medium / EXPENSIVE
  triggers:
    - domain: {trigger_domain}
      trigger: "{trigger condition description}"
  use_when:
    - "{applicable scenario 1}"
    - "{applicable scenario 2}"
  avoid_when:
    - "{inapplicable scenario}"

4. Strategy Selection Guide

5. Tool Templates

Read-only analysis (e.g. code review, security audit):

tools:
  - read
  - grep
  - glob

Read-only + network (e.g. documentation lookup, threat intelligence):

tools:
  - read
  - grep
  - glob
  - bash
  - websearch
  - webfetch

Full execution (e.g. code generation, refactoring):

tools:
  - read
  - grep
  - glob
  - edit
  - bash
  - websearch
  - webfetch

Tool naming rules:

• Prefer the exact tool names currently registered in the system; do not guess or invent names.
• For ThreatBook MCP tools in this project, use the concrete prefixed names such as threatbook_mcp_ip_query and threatbook_mcp_hrti_query.
• More generally, when an MCP server in the project has a stable prefix convention, keep that prefix in agent YAML instead of replacing it with a generic alias.
• Do not mix the old permission style and the new tools style in the same agent unless there is a very specific reason.

6. Validation

After generating files, verify:

1. YAML syntax: run python3 -c "import yaml; from pathlib import Path; yaml.safe_load(Path('~/.flocks/plugins/agents/{name}/agent.yaml').expanduser().read_text(encoding='utf-8'))"
2. Prompt file exists: confirm ~/.flocks/plugins/agents/{name}/prompt.md has been created
3. Directory structure: ensure files are inside ~/.flocks/plugins/agents/{name}/, NOT as flat files like agents/{name}.yaml
4. Name uniqueness: ensure no collision with built-in agents (reserved names: rex, hephaestus, oracle, librarian, explore, prometheus, multimodal-looker, rex-junior, build, plan, compaction, title, summary)
5. Tool names: verify every listed tool exists in the current registry; if the repo exposes a /tools or tool listing command, check against that instead of relying on memory

7. Output

After creation, inform the user:

• File paths created (e.g. ~/.flocks/plugins/agents/{name}/agent.yaml and prompt.md)
• Agent name and role
• Can be invoked via delegate_task(subagent_type="{name}", ...)

Constraints

• Agent names must be kebab-case (lowercase letters + digits + hyphens)
• mode is always subagent (this skill only creates sub-agents)
• Files MUST be written to ~/.flocks/plugins/agents/<name>/ subdirectory — flat files like agents/<name>.yaml are legacy and should NOT be created
• The subdirectory name must match the agent name field exactly
• Do not create agents with names that collide with built-in agents
• Prefer tools: over permission: for new agents so the config stays aligned with the current UI and loader behavior