# Agent Templates

A **template** is a reusable folder you stamp into a working agent group: it
carries the agent's standing instructions, its MCP tool servers, its skills,
and optional recurring tasks, but **no secrets and no provider**. Point `ncl` at one and
you get a configured agent in seconds; you choose the runtime/provider
separately.

Templates are purely additive and require no DB migration. **Templates
are resolved only from a local directory**: `templates/` at the
project root by default (committed but shipped empty), or whatever
`NANOCLAW_TEMPLATES_DIR` points at (a local path only). The public registry
([`nanocoai/nanoclaw-templates`](https://github.com/nanocoai/nanoclaw-templates))
is a manual copy source — clone or download it yourself and copy the chosen
template into your local `templates/` before stamping.

## Using a template

**Via the CLI:**

```bash
ncl groups create --template sales/sdr --name "SDR Agent"
```

This stamps the group but does **not** wire it to a channel. Run
`/manage-channels` (or `ncl wirings create`) afterward, exactly as for a
hand-built group.

### The template ref

`--template <ref>` is a path **relative to the local templates directory**
(`templates/` by default, or `NANOCLAW_TEMPLATES_DIR`). Refs are multi-segment,
e.g. `sales/sdr` → `templates/sales/sdr`.

For safety the ref must stay inside the templates directory: absolute paths, a
leading `~`, and `../` escapes are rejected. There is no `--source`, no git URL,
and no remote fetch at `ncl` time. Populate `templates/` first (by hand, e.g.
copying from the public registry), then stamp.

`NANOCLAW_TEMPLATES_DIR` may point the library at another **local** directory; it
is never a URL and never changes at runtime.

## What's in a template

The full authoring reference lives in the
[templates repo README](https://github.com/nanocoai/nanoclaw-templates#anatomy-of-a-template).
The short version: only `context/instructions.md` is required; everything else
is optional and defaults sensibly:

```
<template>/
├── context/
│   ├── instructions.md        # REQUIRED: the agent's standing persona; marks the folder as a template
│   └── additional_context/    # optional: extra .md files, referenced from instructions.md by relative path
│       └── *.md
├── .mcp.json             # optional: MCP servers (command + args), NO secrets
├── skills/<name>/        # optional: one folder per skill (SKILL.md + any references/), copied whole
├── tasks/*.md             # optional: recurring tasks, created paused
└── README.md             # recommended: per-template docs
```

| Path | Loaded as | Required |
|------|-----------|----------|
| `context/instructions.md` | The agent's persona, prepended to its `CLAUDE.md`/`AGENTS.md` every spawn (system-prompt tier, any provider) | **Yes** |
| `context/**/*.md` (others) | Extra context, copied into the agent's workspace with the same layout relative to `instructions.md` | No |
| `.mcp.json` → `mcpServers` | MCP tool servers (written verbatim to container config) | No |
| `skills/<name>/` | A skill, auto-triggered by its `description` | No |
| `tasks/*.md` | Recurring scheduled tasks, created paused pending user activation | No |

Notes:

- **No provider, model, effort, or packages in a template.** Those are set on
  the agent later via `ncl groups config update`. The runtime defaults to the
  install's configured provider.
- **Keep `instructions.md` focused (under ~200 lines).** It's always in the
  agent's prompt, and some providers cap that doc (Codex ~32 KB), so an over-long
  persona gets truncated. Put bulk material in `skills/` or extra context files instead.
- Skills are copied into the agent's own skills overlay, keyed to that group,
  never shared across groups.

### Recurring tasks

Each immediate Markdown file under `tasks/` defines one recurring task. The
filename becomes its readable name, the frontmatter supplies its cron schedule,
an optional script can decide whether to wake the agent, and the Markdown body
is the prompt:

```markdown
---
schedule: "*/15 * * * *"
script: |
  if [ -f /workspace/agent/wake-next-task ]; then
    echo '{"wakeAgent": true}'
  else
    echo '{"wakeAgent": false}'
  fi
---

Investigate the alerts reported by the script and notify me if they are serious.
```

`schedule` is required. `script` is optional and may be a single-line or
multiline YAML string. The frontmatter accepts no other fields, so typos cannot
silently change behavior. Task files are template input, like `.mcp.json`: they
are not copied into the agent workspace after stamping.

Template tasks use the same creation path as `ncl tasks create`, including cron
validation, the install timezone, first-run calculation, isolated task sessions,
the run-log prompt, script behavior, and frequency limits. Ungated tasks are
limited to four fires in the next 24 hours; tasks with a script gate may run more
often. Templates do not expose the dangerous frequency override or one-time
tasks.

The script is passed unchanged to NanoClaw's normal task creation and execution
path. See [Scheduled Tasks](scheduled-tasks.md#script-gates) for the script
contract, testing workflow, frequency limit, and failure behavior. Avoid putting
secrets directly in scripts; prefer runtime credential injection through OneCLI.

Tasks start **paused**, so stamping a template never starts background work
without user consent. Until the setup welcome flow offers activation, inspect
and enable them with the existing task CLI:

```bash
ncl tasks list --group <agent-group-id> --status paused
ncl tasks resume <task-id>
```

Resuming preserves NanoClaw's normal pause/resume semantics: if the stored next
run passed while paused, the task is eligible immediately.

### Referencing extra context files

Extra `.md` files under `context/` (by convention in an `additional_context/`
subfolder) are copied into the agent's workspace preserving their position
relative to `instructions.md` — a template file at
`context/additional_context/pricing.md` is readable by the agent as
`additional_context/pricing.md`, the same relative path you'd use from
`instructions.md` itself. Nothing is injected automatically: the agent only
reads an extra file if `instructions.md` points to it, so reference every file
you ship.

```markdown
Pricing rules live in `additional_context/pricing.md`. Read it before quoting a price.
```

Context files are copied when you stamp, so files added to the template later
won't reach an already-created agent. Re-stamp the same name to update it.

## MCP servers and credentials

**Templates declare MCP servers, not secrets.** `.mcp.json` carries `command` +
`args` only:

```json
{
  "mcpServers": {
    "hubspot": { "command": "npx", "args": ["-y", "@hubspot/mcp-server"] },
    "exa":     { "command": "npx", "args": ["-y", "exa-mcp-server"] }
  }
}
```

Credentials are held by the **credentials proxy** and injected into outbound
HTTPS calls at the proxy boundary, matched by API host, at request time. The key
never sits in `.mcp.json`, the container env, or chat context. See
[the credentials proxy section in CLAUDE.md](../CLAUDE.md#secrets--credentials--onecli)
for the model.

Two ways a credential gets connected:

1. **Up front.** Register the secret with the credentials proxy (its web UI or
   CLI), matched to the service's API host (e.g. `api.example.com`). Matching
   credentials are injected automatically, so usually nothing else is needed.
2. **On demand (the common path).** Don't set anything up first. The first time
   the agent calls a service with no credential, the API returns **401/403** and
   the agent replies with a prefilled connect link for that host. The user opens
   it, pastes the key, and asks the agent to retry. The key lands in the
   credentials proxy, which injects it on every later call.

### MCP servers that require an env var to boot

Some MCP servers refuse to start unless an env var is *present*, even though the
real credential should come from the credentials proxy, not the env. Because `.mcp.json`'s `env`
block passes through verbatim to the agent's container config, put a **placeholder
value** there to satisfy the boot check:

```json
{
  "mcpServers": {
    "acme": {
      "command": "npx",
      "args": ["-y", "@acme/mcp-server"],
      "env": { "ACME_API_KEY": "placeholder" }
    }
  }
}
```

The server starts; its real outbound calls are still authenticated by the
credentials proxy. **Never put a real key in `env`**: a placeholder only, and only when
the server won't boot without one.

### Approval-gating sensitive actions

The credentials proxy can *hold* a credentialed outbound request and require a
human to approve it before it leaves the proxy: enforcement the agent can't talk
around. This is matched on the outbound HTTP request (host + method + path),
configured on the credentials proxy, and answered by NanoClaw (it DMs an approver). The host side is
already wired; see
[the credentialed-approval flow in CLAUDE.md](../CLAUDE.md#requiring-approval-for-credential-use)
and the [`sales/sdr` template README](https://github.com/nanocoai/nanoclaw-templates/blob/main/sales/sdr/README.md)
for a worked example.

## Contributing a template

Templates ship in the separate
[`nanocoai/nanoclaw-templates`](https://github.com/nanocoai/nanoclaw-templates)
repo, not this one. To add one: fork that repo, drop a folder at
`<category>/<template>/` with at least `context/instructions.md`, test it end to
end (copy it under `templates/` and run
`ncl groups create --template <category>/<template> --name Test`), confirm
any predefined tasks appear under `ncl tasks list --status paused`, confirm no
secrets are committed, and open a PR. The repo's README has the full anatomy,
category conventions, and checklist.