Skip to content
Skills Library
AI & agents · Building & coding

agent-builder

/agent-builder

Create new sub-agents (subagents) by generating YAML config and prompt files in ~/.flocks/plugins/agents/. The created agent can be delegated to by Rex via delegate_task. Use when the user asks to create, add, or generate a new agent.

Repository
flocks ↗
Licence
Apache-2.0
Last repository change
19.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 19.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Create new sub-agents (subagents) by generating YAML config and prompt files in ~/.flocks/plugins/agents/. The created agent can be delegated to by Rex via delegate_task. Use when the user asks to create, add, or generate a new agent.

Original author description

Create new sub-agents (subagents) by generating YAML config and prompt files in ~/.flocks/plugins/agents/. The created agent can be delegated to by Rex via delegate_task. Use when the user asks to create, add, or generate a new agent.

How it works

  1. Workflow
  2. Constraints
Original SKILL.md headings · 196 lines, 985 words
SKILL.md preview
---
name: agent-builder
group: 系统辅助
category: system
description: Create new sub-agents (subagents) by generating YAML config and prompt files in ~/.flocks/plugins/agents/. The created agent can be delegated to by Rex via delegate_task. Use when the user asks to create, add, or generate a new agent.
---

# 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

Versions

RepositoryScoreLicence
This page · agentflocks/flocks100Apache-2.0
railtownai/railtracks100MIT
shareai-lab/learn-claude-code100MIT
baddelta/agent-builder100MIT
mathews-tom/armory100MIT
DineshKuppan/claude-skill-library100MIT
naveedharri/benai-skills100MIT
testdouble/han100MIT
pr-pm/prpm91MIT

Database snapshot: 13.11.2026 · package version a2b393622d8f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90pi-rex-agents
    Use when delegating to subagents, supervising child agents, or managing worktrees inside Rex. Explains Rex placement (same-tab block vs new tab), automatic result delivery, and why child agents are leaves.
  • 100device-integration-guide
    指导 Flocks 新建、添加和接入安全设备。Use when the user asks to create, add, onboard, or connect a new security device.
  • 100rex-subagents
    Spawn interactive pi subagents in separate Rex panes using pi agent definitions (.pi/agents/*.md, ~/.pi/agent/agents/*.md such as scout, worker, reviewer, planner). Runs them in parallel in the background, shows them in a status widget, delivers their results back to you…
  • 95workflow-builder
    根据自然语言描述生成 flocks 内置工作流(workflow.md, workflow.json)。当用户提出创建/设计/生成/搭建工作流或任何多步骤流程(如告警调查、事件响应、SOP/Runbook 自动化)时使用本 skill。
  • 100rex-teams
    Work with other agents inside Rex. Start Claude, Codex, Pi, or other agent CLIs as subagents in background tabs, message them mid-task, and get woken when they report back. Also message teammates, the long-running agents a user has set up in labeled Rex tabs or panes (a PM, an…
  • 100rex-agent
    Manage AI agent fleets in a Rex terminal: tile root + workers in one tab, start/prompt/wait/read them, check what they do, steer fleet panes; `help` lists all. Don't use for Herdr, tmux, or one-off Rex tabs, splits or commands.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.