nanoclaw/docs/templates.md

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, and its skills, but no secrets and no provider. Point ncl (or the setup wizard) at one and you get a configured agent in seconds; you choose the runtime/provider separately.

Templates are purely additive: no DB migration, no new dependency. At runtime, 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 setup wizard can also discover templates from the public registry (nanocoai/nanoclaw-templates) and copy a chosen one into your local templates/ before stamping.

Using a template

During install. bash nanoclaw.sh opens the setup wizard. Choose Template setup, then either NanoClaw template library (clones the public registry, copies the template you pick into your local templates/) or Local templates (lists what's already in templates/). The normal auth step then picks the runtime, and the wizard stamps and wires your first agent.

Anytime, via the CLI:

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, or via the setup wizard's library option), 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. 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
└── 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

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.

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.

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:

{
  "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 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:

{
  "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 and the sales/sdr template README for a worked example.

Contributing a template

Templates ship in the separate 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 no secrets are committed, and open a PR. The repo's README has the full anatomy, category conventions, and checklist.