Agent Templates

An agent template is a reusable bootstrap that initializes a new agent's AGENTS.md role contract and optional pre-installed skills. Templates give new agents a known starting point without manual setup.

When to Use Templates

Use --template when you want a new agent to start with a specific role and capabilities. Without a template, agents start with a generic default contract.

Common scenarios:

• Creating a synced reviewer agent — holon agent create reviewer --template holon-reviewer
• One-shot tasks with a role — holon run --template holon-developer "Fix the null check in handler.rs"
• Solving GitHub issues — holon solve --template holon-github-solve https://github.com/owner/repo/issues/42

Template library and default bootstrap

Holon keeps visible templates in the user template library:

~/.agents/agent_templates/
  .registry.json
  <install_id>/

User-authored templates, explicit installs, and remote-source sync results all use this same root. Remote-source sync is equivalent to a batch install/update of managed templates into that library. Holon writes .registry.json metadata in the root to track synced remote sources, installed template mappings, and content hashes.

Template IDs stay local to their source. If a synced remote template conflicts with an existing local directory, Holon keeps the remote template_id in metadata and installs it under a deterministic local install_id, such as worker@official. Re-syncs reuse the recorded install id. If a managed template has local edits, sync refuses to overwrite it until the operator resolves the dirty copy.

Holon also carries one hidden built-in holon-default template for zero-config and offline startup. It is not seeded into ~/.agents/agent_templates, and it is not shown as a catalog entry. It is used only when creating an agent without an explicit template selector.

The official template source is the Holon repository. When synced, templates under its top-level agent_templates/ directory become normal local catalog entries from ~/.agents/agent_templates.

Using --template

Create an Agent

holon agent create reviewer --template holon-reviewer

This initializes ~/.holon/agents/reviewer/AGENTS.md from the local holon-reviewer template after that template has been installed or synced. If the agent home already exists and is non-empty, template initialization refuses to overwrite it.

One-Shot Run

holon run --template holon-developer "Fix the null check in handler.rs"

The agent is created with the developer role contract, executes the prompt, and is cleaned up after completion.

Solve a GitHub Issue

holon solve --template holon-github-solve https://github.com/owner/repo/issues/42

The agent starts with GitHub workflow guidance and the four GitHub skills pre-installed.

Template Structure

A template consists of a directory containing:

my-template/
├── AGENTS.md       # Required — the agent role contract
├── template.toml   # Optional — display metadata and compatibility
└── skills.toml     # Optional — skill references to pre-install

AGENTS.md

The agent's role contract. This is the same format as any agent's AGENTS.md. The runtime appends the standard Agent Home guidance automatically, so your template only needs to define the role-specific content.

template.toml

An optional manifest for template metadata such as display name, summary, schema, and compatibility. Synced remote templates use it for catalog metadata; path-based local templates can omit it and fall back to directory/AGENTS.md metadata.

skills.toml

An optional manifest that lists skills to pre-install when the agent is created:

[[skills]]
kind = "github"
repo = "holon-run/holon"
path = "skills/github-issue-solve"
ref = "main"

[[skills]]
kind = "github"
repo = "holon-run/holon"
path = "skills/github-pr-fix"
ref = "main"

[[skills]]
kind = "github"
repo = "owner/skills"
path = "skills/custom-skill"
ref = "v1.2.3"

[[skills]]
kind = "github"
uses = "holon-run/holon/skills/ghx@main"

[[skills]]
kind = "local"
path = "/absolute/path/to/custom-skill"

Two skill reference kinds are supported:

• github — A skill fetched from a GitHub repository path. Use repo = "owner/repo", path = "path/to/skill", and optional ref as the canonical form. Templates may also use uses = "owner/repo/path@ref" as a GitHub Actions-style shorthand; Holon normalizes it to repo/path/ref. Holon also accepts owner/repo/path#ref and GitHub tree URLs as compatible input forms, but it does not use the owner/repo@skill shorthand where @ names a skill.
• local — An absolute path to a skill directory on disk

kind = "builtin" is no longer part of the template manifest format. Official Holon skills are referenced the same way as any other GitHub-hosted skill, for example repo = "holon-run/holon" and path = "skills/ghx".

Creating Custom Templates

Create a directory with an AGENTS.md, optional template.toml, and optional skills.toml, then use the absolute path as the template selector:

holon agent create my-agent --template /path/to/my-template

You can also host templates on GitHub and reference them by URL:

holon agent create my-agent --template https://github.com/owner/repo/tree/main/templates/my-template

Templates referenced by absolute path or GitHub URL record provenance in the agent home (template-provenance.json), so you can trace back where the agent's contract came from.

Templates vs Skills

Templates and skills serve different purposes:

Templates often include skill references so that new agents have the right tools available from the start. See the Skills guide for details on skills.