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: ```markdown 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. ```yaml # 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 | Strategy | Use Case | Tool Scope | Example Agents | |----------|----------|------------|----------------| | `read_only` | Analysis/consultation only, no file mutations | Read-only tools | oracle, librarian | | `react` | General execution, observe-think-act loop | All tools | general | | `plan_and_execute` | Complex tasks requiring planning before execution | All tools | rex, hephaestus | | `explore` | Codebase exploration and search | Search/read tools | explore | ### 5. Tool Templates **Read-only analysis** (e.g. code review, security audit): ```yaml tools: - read - grep - glob ``` **Read-only + network** (e.g. documentation lookup, threat intelligence): ```yaml tools: - read - grep - glob - bash - websearch - webfetch ``` **Full execution** (e.g. code generation, refactoring): ```yaml 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