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

# Agent templates

> Template structure, files, and how new agents are created from templates.

Templates are role-specific starting points for agents. They live in [`templates/`](https://github.com/yourhq/yourhq/tree/main/templates) and get seeded into the gateway's local git repo as `template/<name>` branches on first boot.

## Template files

| File           | Purpose                                                                      |
| -------------- | ---------------------------------------------------------------------------- |
| `agent.json`   | Runtime metadata: slug, name, description, team, capabilities, browser color |
| `IDENTITY.md`  | Role, voice, and domain behavior                                             |
| `SOUL.md`      | Goals and non-negotiables                                                    |
| `USER.md`      | Owner profile placeholders (filled at provision time)                        |
| `MEMORY.md`    | Starting long-term context                                                   |
| `TOOLS.md`     | Tool-use guidance                                                            |
| `HEARTBEAT.md` | Memory maintenance guidance (scheduled work now handled by Routines)         |
| `AGENTS.md`    | Agent-specific instructions                                                  |
| `skills/`      | Reusable procedures and scripts                                              |

Key scripts in `skills/hq/scripts/`:

| Script                | Purpose                                                                       |
| --------------------- | ----------------------------------------------------------------------------- |
| `hq_skill_upsert.py`  | Create or update agent-scoped skills with auto-embedding and junction linking |
| `hq_search_docs.py`   | Semantic + full-text search across knowledge items                            |
| `hq_create_doc.py`    | Create a new knowledge item (page or skill)                                   |
| `hq_update_doc.py`    | Update an existing knowledge item                                             |
| `hq_inbox_process.py` | Process background inbox items                                                |
| `hq_claim_task.py`    | Claim and start working on a task                                             |

## How provisioning works

When you create an agent, HQ forks the selected template branch into the agent's personal branch, then patches identity fields (`slug`, `name`, `emoji`, `channel`).

### Model resolution at provision time

The model field in `agent.json` is optional. At provision time, `add-agent.sh` resolves the agent's model using this cascade:

1. **CLI argument** — if the `provision` command payload includes `model`, use it
2. **Template's `agent.json`** — if the template specifies a model, use it
3. **Gateway default** — the workspace default from Settings → Connections
4. **First connected model** — detected from `openclaw models status`

After provisioning, you can change the model at any time from the agent detail page → Model section. Changes take effect on the next session without a gateway restart.

<Tip>
  To create a custom template, copy `templates/default/` to `templates/your-role/`, edit the identity files, add role-specific skills, and rebuild the templates index. See [Agents → Writing a new template](/concepts/agents#writing-a-new-template) for the full walkthrough.
</Tip>