agent-builder

What this skill does

# Agent Builder

Build focused micro-agents that do 1-2 things exceptionally well.

## Routing (YOU MUST DECIDE)

When the user asks to create an agent, pick the right path:

**`agent_build` (singular)** — 1 skill, 1 data source, simple recurring tasks, 1-5 tool calls.

**`agent_build` + `always_on=True`** — Agent that runs 24/7, polls inbox for messages every 5 min. Like an employee at their desk.

**`agent_team` (team)** — 2+ skills, parallel data gathering, synthesis needed, 10+ tool calls.

**`agent_loop` (long-running)** — Open-ended research, iterative accumulation, no fixed endpoint.

**`agent_message`** — Send a message to any agent's inbox. Works for user→agent and agent→agent.

**When unsure:** Start singular. Cheapest. User can upgrade later.

## Tools

| Tool | Use |
|------|-----|
| `agent_build` | Create or update an agent. Set `always_on=True` for daemon mode. |
| `agent_task` | Add/update/complete/remove/list tasks. Also `set_status` to pause/archive/reactivate. |
| `agent_run` | Execute agent once (picks highest-priority pending task) |
| `agent_list` | List all agents with status, task counts. Filter by team/status. |
| `agent_team` | Create and run teams (leader + workers with cost-optimized models) |
| `agent_loop` | Run agent in loop mode — iterates until goal satisfied or budget exhausted |
| `agent_message` | Send a message to an agent's inbox. Daemon picks it up on next poll. |

## Singular Agent Workflow

### 1. Create

```
agent_build(
  name="market-scout",
  display_name="Market Scout",
  role="Crypto market surveillance specialist",
  goal="Monitor BTC and ETH prices, flag anomalies",
  skills=["coingecko", "chart"],
  template="monitor",
  mode="research",
  schedule="0 8 * * *",
  timezone="Asia/Kuala_Lumpur"
)
```

**Templates:** `default`, `monitor`, `researcher`

**Modes:**
- `default` — Free thinking
- `research` — Hallucination guardrails: must say "I don't know", cite sources, extract quotes before analysis

**Schedule:** Cron (`"0 8 * * *"`), interval (`"every 30 minutes"`), delay (`"in 2 hours"`), at (`"at 2026-05-01 14:00"`)

### 2. Add Tasks

```
agent_task(agent="market-scout", action="add",
  title="Check BTC price",
  priority="high",
  due_date="2026-04-26",
  recurring=True,
  depends_on=["task-id-of-prerequisite"]
)
```

- **Priority:** `low` (60s, 2 calls), `medium` (120s, 5 calls), `high` (180s, 10 calls), `critical` (300s, 20 calls)
- **Recurring:** Resets to pending after completion, logs history
- **depends_on:** Task chaining — blocked until dependencies complete

### 3. Run

```
agent_run(agent="market-scout")
```

### 4. Manage

```
agent_task(agent="market-scout", action="set_status", status="paused")
agent_list(team="market-sentiment", verbose=True)
```

## Team Workflow

### 1. Create Team

```
agent_team(action="create",
  name="market-sentiment",
  leader={"name": "analyst", "role": "Synthesize sentiment", "skills": ["chart"]},
  workers=[
    {"name": "btc-fetcher", "role": "Fetch BTC tweets", "skills": ["twitter"]},
    {"name": "eth-fetcher", "role": "Fetch ETH tweets", "skills": ["twitter"]},
  ]
)
```

Leader: Sonnet ($3/$15). Workers: Haiku ($1/$5). ~67% savings.

### 2. Run Team

```
agent_team(action="run", name="market-sentiment",
  goal="Cross-chain sentiment comparison for BTC and ETH"
)
```

Leader owns the full pipeline: creates worker tasks → runs workers → waits (bash poll) → reads outputs → synthesizes.

## Loop Mode (Long-Running)

For open-ended tasks with no fixed endpoint:

```
agent_loop(agent="uni-scout",
  goal="Find universities with AI programs open to collaboration",
  max_iterations=10,
  output_file="candidates.json",
  timeout=1800
)
```

The agent iterates: read progress → search → add results → evaluate → continue/stop.

**Budget regimes** adapt strategy as iterations progress:
- EXPLORE (early) → CONVERGE (middle) → FOCUS (late) → FINALIZE (end)

**Stopping:** Agent says done, max iterations, or 2 consecutive dry iterations.

## Always-On Agents (Daemon Mode)

Create agents that run 24/7, polling for messages and tasks:

```
agent_build(name="ai-scout", display_name="AI Scout",
    role="Research AI content creators on Twitter",
    goal="Build a database of high-quality AI creators",
    skills=["twitter"], template="researcher", mode="research",
    always_on=True, team="marketing"
)
```

Then activate the daemon:
```
scheduled_task(action="activate", job_id="<daemon_job_id from output>")
```

Every 5 minutes, the daemon:
1. Checks `inbox.json` — new messages? Process them, respond, push to user.
2. Checks `tasks.json` — pending tasks? Run the highest priority one.
3. Neither? **Autonomous work** — reads its goal, memory, and existing output, then proactively does the next most valuable thing to advance its goal. Runs every 30 min (cooldown prevents burning tokens every poll).

If the agent has nothing productive to do (goal fully satisfied), it outputs `AUTONOMOUS_IDLE` and costs $0.00.

## Messaging

Send messages to any agent — user to agent or agent to agent:

```
agent_message(agent="ai-scout", message="Focus on creators with 100K+ followers who post about LLMs")
agent_message(agent="marketing-lead", message="5 new creators found", from_agent="ai-scout")
```

Messages queue in `inbox.json`. The agent's daemon processes them on next poll (~5 min max).
Responses appear in `outbox.json` and push to user.

## Managing Agents

Everything is mutable at any time:
- **Pause:** `agent_task(agent="x", action="set_status", status="paused")` — daemon skips paused agents
- **Resume:** `agent_task(agent="x", action="set_status", status="active")`
- **Kill daemon:** `scheduled_task(action="cancel", job_id="<id>")` — **cancel is permanent**, see Daemon Lifecycle below
- **Change role/skills/mode:** Re-run `agent_build` with new params — overwrites config
- **Send new instructions:** `agent_message(agent="x", message="change focus to...")`
- **Check findings:** `read_file("agents/team/agent/output/results.json")`
- **Delete:** Remove the directory — agents are just files

### Daemon Lifecycle (IMPORTANT)

**Cancel is permanent.** `scheduled_task(action="cancel")` deletes the job. You cannot reactivate it. To restart a cancelled daemon:
1. Re-run `agent_build` with `always_on=True` — registers a new scheduled task
2. The new task gets a new `job_id` — the old run.py's `JOB_ID` is now stale
3. `agent_build` automatically writes the correct `JOB_ID` into the new run.py
4. Activate: `scheduled_task(action="activate", job_id="<new_id>")`

**JOB_ID must match the active task.** The `JOB_ID` inside run.py is how push notifications route to the right job. If you manually copy a run.py, update the `JOB_ID` constant or push notifications silently go to a dead job.

## Agent Pre-Action Reasoning

Every agent template now includes a mandatory reasoning framework before tool calls:
- **WHO** is affected?
- **WHAT** exactly will you do?
- **WHY** does this advance your goal?
- **RISK** — safe / moderate / destructive?

Destructive actions (delete, overwrite, clear) require the agent to STOP and generate a preview before executing. This prevents accidental data loss.

## Output Contract

Every agent has a **mandatory output contract** baked into its prompt:
- Primary output is always a JSON file (`output/results.json`)
- JSON first, human-readable summary second
- On every run: read existing → append new → write back (never overwrite from scratch)
- Downstream agents and systems read JSON, not markdown

This prevents the "beautiful report but empty database" problem where agents write prose but never update their structured output.

## Deduplication

All templates instruct agents to check for duplicates before adding items:
- Match on primary identifier (name, handle, URL, or ID)
- Skip duplicates, log skip count
- Design dedup in from run 1, not as a cleanup pass later

## Resource Ownership

One agent owns one resource. Rules baked into every template:
- Agents write ONLY to thei