> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nanoclaw.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Submitting a template

> Contribute a template to the public NanoClaw registry: how acceptance and ownership work, where it goes, the standards CI enforces, the paid-service and monetization rules, and the PR checklist.

Templates ship in [`nanocoai/nanoclaw-templates`](https://github.com/nanocoai/nanoclaw-templates), a separate repo from NanoClaw itself. Contributions are accepted by pull request, and CI enforces most of the standards below automatically.

Build and test the template first — see [Building a template](/templates/building). This page covers only what the registry adds on top.

## Acceptance and ownership

Read this before you invest the work. Two things about the registry are worth knowing up front.

### Acceptance is at NanoClaw's discretion

The catalog is curated, not a free-for-all. A submission has to bring real value to the community: it should do a job people actually have, work out of the box, and be more than one team's internal configuration. A well-built template can still be declined — because it's too narrow, because it substantially duplicates one already in the catalog, or because the catalog doesn't need it yet.

<Tip>
  Unsure whether an idea fits? Open an issue describing it before building the whole thing. That's cheaper than finding out at review.
</Tip>

### Accepted templates become NanoClaw's to maintain

Once a template is merged it is part of the catalog, and NanoClaw takes over responsibility for it. That means we may edit, restructure, retarget, recategorize, or retire it — updating a pinned MCP server version, rewriting a persona, folding it into another template — **without asking first**, the same as any other file in the repo.

This isn't a formality. People stamp these templates expecting them to keep working, so the catalog has to stay maintainable as a whole, and that is only possible if the maintainers can change any part of it.

Concretely, after merge:

| | |
| - | - |
| Ongoing maintenance and support | NanoClaw |
| Deciding when it changes, moves, or is retired | NanoClaw |
| Fixing it when an upstream dependency breaks | NanoClaw |
| Authorship credit | Yours, permanently |

### You keep the credit

Attribution is preserved through every later edit. Record it in the manifest, which supports an `author` object per the Agent Plugins spec:

```json theme={null}
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "acme-agent",
  "author": { "name": "Your Name", "url": "https://github.com/your-handle" }
}
```

`author` takes `name`, `email`, and `url` — any subset, and any other field is rejected. Add a credit line to the template's `README.md` too if you'd like it visible to people reading the folder. Neither gets stripped when the template is later edited.

<Note>
  The registry is [MIT licensed](https://github.com/nanocoai/nanoclaw-templates/blob/main/LICENSE), and your contribution is accepted under that same license — so "ownership" here means stewardship and maintenance, not a transfer of copyright. Your work stays MIT, attributed to you, and anyone may fork it.
</Note>

## Where it goes

Every template lives under a **category** folder, one folder per template, at exactly two levels:

```text theme={null}
<category>/<template>/
```

That path is also the ref people pass to `--template`: a template at `<category>/<template>/` is stamped with `--template <category>/<template>`. The engine stamps a more deeply nested ref fine, but the registry checks walk exactly two levels — nest deeper and the parent fails CI with `not a template: plugin.json missing`.

Categories in the registry today are `data`, `engineering`, `finance`, `hr`, `it`, `lifestyle`, `media`, `misc`, `operations`, `product`, `sales`, `security`, `social-media`, and `support`. Templates currently live under `data`, `engineering`, `lifestyle`, `media`, `product`, and `sales`; the other categories hold only a README.

<Tip>
  Check whether an existing category fits and reuse it before adding a new one. A new category must be a single, lowercase, broadly-recognized business function — `sales`, `support`, `engineering`, `marketing`, `ops`, `finance` — never a niche or product-specific label. The goal is a small, predictable set a newcomer can guess.
</Tip>

## What the registry requires

`plugin.json` is the only required file. Everything else is optional to the loader, but the registry holds contributions to a higher bar than the engine does.

| Path | Standard | Enforced by |
| - | - | - |
| `plugin.json` | Present, with the exact 1.0.0 `$schema` and a valid `name` | CI |
| `mcp.json` | Exact MCP `$schema`, exactly two top-level fields, a declared `type` per server | CI |
| `mcp.json` credentials | Credential-shaped `env`/`headers` values carry the literal `"placeholder"` | CI |
| `skills/<name>/SKILL.md` | Present, with `name` and `description` frontmatter | CI |
| `ai.nanoco.nanoclaw/tasks/*.md` | `schedule` frontmatter, optional `script`, no other fields, non-empty body | CI |
| Whole tree | No symlinks | CI |
| `index.json` | Generated by `node scripts/build-index.mjs` and committed whenever a template is added, moved, or removed. Never hand-edited. | CI |
| `plugin.json` `version` | Bumped when you change a template that is already in the registry. New templates are exempt. | CI |
| `ai.nanoco.nanoclaw/context/instructions.md` | Optional. If shipped, it is non-empty | CI (only when the file exists) |
| `README.md` | Explains what the template does, and for every service it needs: the API host, auth style, exact scopes, and where to get the key | Review |
| `README.md` paid dependencies | Any paid service is declared up front, with a link and the required tier — see below | Review |
| Whole template | No affiliate links, baked-in billing, or author monetization | Review |

## Paid services and monetization

A template may depend on paid MCP servers or paid API tiers. That is fine. What isn't fine is a user discovering the paywall after they've stamped it.

**The template's `README.md` must state, up front:**

* that the service is paid,
* a link to the tool,
* and which plan or tier the template needs, where the vendor gates the required capability behind one,
* and that the user supplies **their own key**.

Never ship a shared key, a template-owner key, or any credential the contributor controls. The user's key goes in their own [OneCLI Agent Vault](/operate/credentials) and stays there.

<Tip>
  **Name the tier, don't quote the price.** Prices change and a stale figure in a README is worse than none — link the vendor's pricing page and name the plan instead. Tier names are far more stable than dollar amounts.
</Tip>

If the template works on a free tier with reduced capability, say which parts need the paid plan. That's more useful than a blanket "requires a paid subscription."

<Warning>
  **No monetization through the registry template.** No affiliate or referral links, no baked-in billing, no revenue share wired into the template. A registry template is a configuration people can read and fork, not a distribution channel for the author.
</Warning>

## Run the checks locally

The registry ships the same script CI runs. It has zero dependencies — plain Node:

```bash theme={null}
node scripts/check-templates.mjs
```

It walks every `<category>/<template>/` folder and reports all problems at once, exiting non-zero if any are found (listing order follows the filesystem, not the alphabet):

```text theme={null}
check-templates: 4 template(s) OK: <category>/<template>, …
```

CI runs three jobs: this script, an index check, and a version-bump check. You can run all three locally. After the script above, regenerate the index and confirm it is clean, then check the version bump against the branch you are merging into:

```bash theme={null}
node scripts/build-index.mjs
git diff --exit-code index.json
node scripts/check-version-bump.mjs main
```

Commit the regenerated `index.json` whenever you add, move, or remove a template. The version-bump check only applies when you edit a template that is already in the registry.

Beyond the standards above, it also catches two migration mistakes: a `.mcp.json` that should be renamed to `mcp.json`, and a `context/instructions.md` with no `plugin.json` — the [pre-plugin layout](/templates/building#migrating-from-the-pre-plugin-layout).

## Open the PR

<Steps>
  <Step title="Fork and branch">
    Fork the registry and create a branch for your template.
  </Step>

  <Step title="Build it">
    Follow [Building a template](/templates/building) — `plugin.json` first, then `mcp.json`, `skills/<name>/`, tasks, and a `README.md`. Put it at `<category>/<template>/`, and leave the provider unset.
  </Step>

  <Step title="Check and test">
    Run `node scripts/check-templates.mjs`, then [stamp and drive it against a real install](/templates/building#testing-locally).
  </Step>

  <Step title="Re-read the diff">
    Scan for secrets one more time before you commit.
  </Step>

  <Step title="Open the PR">
    Describe what the template does, including any predefined tasks and the MCP servers and credentials it expects. Set `author` in `plugin.json` so the credit lands with the template.
  </Step>
</Steps>

Before requesting review, confirm each of these:

* [ ] The template lives under an appropriate `<category>/<template>/`, reusing an existing category where one fits.
* [ ] `plugin.json` is present with the exact 1.0.0 `$schema` and a valid `name`.
* [ ] If the template ships `ai.nanoco.nanoclaw/context/instructions.md`, it is non-empty and stays focused — under roughly 200 lines, with bulk material in `skills/` or `additional_context/`.
* [ ] Every `mcp.json` server declares a `type`, and every credential-shaped `env`/`headers` value is the literal `"placeholder"`.
* [ ] Every task file has a non-empty `schedule`, an optional non-empty `script`, no other frontmatter fields, and a prompt body.
* [ ] A per-template `README.md` explains the template, and for every service it needs gives the API host, auth style, exact scopes, and where to get the key.
* [ ] Any `"placeholder"` env var is there because the server won't boot without it — and the README says never to replace it with a real key.
* [ ] Every paid service is declared up front in the README: that it's paid, a link to the tool, the tier the template needs (if any), and that the user brings their own key. No prices quoted.
* [ ] No affiliate or referral links, no baked-in billing, and no shared or author-owned credential anywhere in the template.
* [ ] `node scripts/check-templates.mjs` passes.
* [ ] The template has been [stamped and tested locally](/templates/building#testing-locally) with a bare ref.
* [ ] No API keys, tokens, or other secrets appear anywhere in the diff.
* [ ] You've read [Acceptance and ownership](#acceptance-and-ownership): acceptance is discretionary, and a merged template is NanoClaw's to maintain, with your authorship credited permanently.

## Related pages

<CardGroup cols={2}>
  <Card title="Building a template" icon="pen-ruler" href="/templates/building">
    Build one and test it before you submit.
  </Card>

  <Card title="Template format reference" icon="book" href="/reference/template-format">
    The rules the engine validates, as distinct from registry policy.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.