Skip to main content
A template is a reusable directory you stamp into a working agent. 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 group in seconds.
Templates use the Agent Plugins 1.0.0 format. Templates written for the earlier layout (a bare context/instructions.md marker and .mcp.json) are no longer read — see migrating from the pre-plugin layout.

​
Why the format is a standard

Templates are Agent Plugins 1.0.0 directories. The portable surface — skills and mcp.json — follows the spec exactly. Everything NanoClaw-specific (persona, extra context, scheduled tasks, display name) rides in the spec’s own extension mechanism, under the ai.nanoco.nanoclaw namespace. That cuts both ways, which is the point:

A NanoClaw template is a conformant plugin

Drop it into any other spec-compatible client and its skills and MCP servers load. The NanoClaw extras are ignored by rule, not by accident.

A conformant plugin is a stampable template

Only plugin.json is required. A persona-less third-party plugin stamps as a new agent group with its skills and MCP servers; the NanoClaw-only slots stay empty.

​
What a template carries

Only plugin.json is required — it is the manifest and the discovery marker. Everything else is optional and defaults sensibly. See Building a template for the full anatomy and the template format reference for field-level rules.

​
What a template deliberately does not carry

Because the provider is chosen separately, one template works on any provider.

​
Templates create new agents only

A template is only ever used to create an agent. There is no way to adopt one onto an agent that already exists:
  • An agent you built by hand (ncl groups create --folder …) can never receive a template.
  • An agent stamped from one template can never be switched to a different one.
The only ongoing operation is restamping — pulling a newer version of the same template into the agent that template created. Targeting anything else fails:
If you have an existing agent and want what a template offers, stamp a new agent from the template and wire it up alongside — or copy the pieces you want in by hand.

​
Where templates come from

Templates resolve only from a local directory — templates/ at the project root by default (committed, and ships with just a README), or whatever NANOCLAW_TEMPLATES_DIR points at. There is no git URL, no --source, and no remote fetch at ncl time. The public catalog is nanocoai/nanoclaw-templates. Get a template from it into your local templates/ one of two ways:
  • The setup wizard’s library picker clones the registry and copies your pick into templates/ for you.
  • By hand — clone or download the repo and copy the template folder across.
Then stamp it with its bare ref. See Using a template, or Getting started with a template for the guided path from a fresh machine.

​
The catalog today

Templates live under a <category>/<template>/ folder, and that path is exactly the ref you pass to --template. The catalog moves faster than these docs — check the repo for the current list.

​
Next steps

Using a template

Stamp an agent during install or anytime with ncl, then wire it up and activate its tasks.

Updating a stamped agent

Restamp in place when the template changes — what resets, what is never touched.

Building a template

Build one: manifest, MCP servers, skills, persona, tasks, and the no-secrets rule.

Template format reference

Field-level validation rules, limits, and the runtime contract.
Last modified on August 13, 2026