# VeilCLI Examples

Reference examples covering every agent feature. Copy what you need into your `.veil/` workspace folder.

---

## Agents

### `agents/hello/` — Minimal Reference
The simplest possible agent — no tools, chat only. Use this to verify your server is working and as a starting point when reading the docs.

**Demonstrates:** `agent.json` basics, `AGENT.md` with variable substitution (`$PROJECT_ROOT`)

---

### `agents/assistant/` — Full General-Purpose Agent
A complete agent with all four modes enabled (chat, task, subagent, daemon). Shows the full `agent.json` surface: `tools`, `permissions`, `allowedAgents`, `memory`, `skillDiscovery`, cron scheduling.

Also includes a **`SOUL.md`** — demonstrates splitting stable capabilities (`AGENT.md`) from swappable tone/persona (`SOUL.md`).

**Demonstrates:** All 4 modes, `tools` whitelist, `permissions.deny`, memory, `skillDiscovery`, `SOUL.md`, `allowedAgents`

---

### `agents/researcher/` — Web Research Agent
A task/subagent-optimised agent for systematic web research. Includes an **agent-scoped skill file** at `skills/web-research.md` — loaded via the `skills` array in the mode config.

**Demonstrates:** `skills` per mode, research-focused `AGENT.md` methodology, `memory_write` for persistence, `todo_write` for planning

---

### `agents/orchestrator/` — Multi-Agent Orchestrator
Delegates all work to specialist agents. Uses `agent_spawn` with `wait: false` for parallel fan-out, `task_subscribe` for durable completion tracking, and `task_status` for polling. Does not use file or shell tools — only coordination tools.

**Demonstrates:** `allowedAgents`, `agent_spawn` (async), `task_subscribe`, fan-out decomposition pattern in `AGENT.md`

---

### `agents/monitor/` — Scheduled Daemon
Runs on a cron schedule (`*/15 * * * *`), reads its `heartbeatFile` each tick, checks system health, logs results, and alerts via `agent_message({async_inform: true})`. The `heartbeatFile` is editable at runtime to change behaviour without restarting the daemon.

**Demonstrates:** `daemon` mode, `cron`, `heartbeatFile`, `conflictPolicy`, `alertRouting`, heartbeat instructions file

---

## Skills

Skills are plain Markdown files injected into an agent's system prompt. Add them to an agent via the `skills` or `autoLoadSkills` arrays in a mode config.

```json
"modes": {
  "task": {
    "enabled": true,
    "skills": ["web-research"],
    "autoLoadSkills": ["code-review"]
  }
}
```

VeilCLI looks for skill files in:
1. `<agent-folder>/skills/<name>.md` (agent-scoped)
2. `.veil/skills/<name>.md` (project-scoped)

### `skills/web-research.md`
Search query construction, source quality tiers, fetching strategy, and hallucination avoidance rules. Load into any agent that uses `web_search` / `web_fetch`.

### `skills/code-review.md`
Systematic review checklist: architecture → correctness → security → performance → readability → tests. Includes severity levels (`CRITICAL` / `HIGH` / `MEDIUM` / `LOW` / `NIT`) and output format template.

### `skills/summarise.md`
Format selection by task type, length guidelines, executive summary template, and synthesis rules for combining multiple sources.

---

## Custom Tools

Custom tools extend the built-in tool set. Place a tool folder anywhere the agent can resolve it (agent folder or project `.veil/tools/`), then reference it in the agent or settings config.

A custom tool folder requires exactly two files:
- `tool.json` — name, description, `input_schema` (JSON Schema)
- `index.js` — exports `execute(input)` → `string`

### `tools/word-count/`

```json
{
  "name": "word_count",
  "description": "Count words, characters, and lines in a text string.",
  "input_schema": { ... }
}
```

**How to use it:** Copy the folder to `.veil/tools/word-count/` (or an agent's folder) and add `"word_count"` to the agent's `tools` list. VeilCLI automatically loads and validates it via the tool registry.

**Demonstrates:** `tool.json` manifest format, `execute(input)` contract, optional injected runtime params (`_cwd`, `_agent`, etc.)

### `tools/summarize_text/`

```json
{
  "name": "summarize_text",
  "description": "Summarize a block of text using the LLM. Optional `style` controls verbosity ('terse' | 'detailed').",
  "input_schema": { ... }
}
```

**How to use it:** Copy the folder to `.veil/tools/summarize_text/` (or an agent's folder) and add `"summarize_text"` to the agent's `tools` list.

**Demonstrates:** Calling the LLM from inside a custom tool. Uses `callWithProviderFallback` from [`llm/provider.js`](../llm/provider.js) and `extractMessage` from [`llm/client.js`](../llm/client.js) — same provider resolution + fallback chain the agent's main loop uses, in-process. See the docs section [Calling the LLM from a custom tool](../docs/guide/06-tools.md#calling-the-llm-from-a-custom-tool) for the full pattern, including cost / budget caveats.

---

## Quick Recipes

**Minimal working agent (chat only):**
```json
{
  "name": "my-agent",
  "model": "anthropic/claude-haiku-4-5",
  "modes": { "chat": { "enabled": true } }
}
```

**Agent with read-only file access:**
```json
{
  "name": "reader",
  "model": "anthropic/claude-haiku-4-5",
  "modes": {
    "task": {
      "enabled": true,
      "tools": ["read_file", "list_dir", "glob", "grep"],
      "maxIterations": 20,
      "maxDurationSeconds": 120
    }
  }
}
```

**Daemon that runs every 5 minutes:**
```json
{
  "name": "ticker",
  "model": "anthropic/claude-haiku-4-5",
  "modes": {
    "daemon": {
      "enabled": true,
      "cron": "*/5 * * * *",
      "maxIterations": 5,
      "maxDurationSeconds": 60,
      "conflictPolicy": "skip"
    }
  }
}
```

---

## Further Reading

- [Agent Configuration](../docs/guide/04-agents.md) — full `agent.json` field reference
- [Built-in Tools](../docs/guide/06-tools.md) — all 24 tools with parameters
- [Permissions](../docs/guide/07-permissions.md) — `tools`, `disallowedTools`, `permissions.allow/deny`
- [Multi-Agent Orchestration](../docs/guide/09-multi-agent.md) — patterns: sync, async fan-out, subscriptions
- [Daemon Agents](../docs/guide/10-daemons.md) — cron, heartbeat, conflict policy