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 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

Built-in Templates

Holon ships with these built-in templates. The repository source lives under builtin_templates/, and at runtime templates resolve from ~/.agents/templates/<template_id>/ (built-in templates are seeded there during initialization).

holon-default

The default template. Provides a fill-in-the-blank AGENTS.md structure with sections for Role, Responsibilities, Authority, Escalation Boundary, and Operating Conventions. Use this as a starting point for custom roles.

holon-developer

Pre-configured for implementation work:

• Turn requirements into concrete code changes
• Run minimal verification that meaningfully checks the change
• Keep edits narrow, explicit, and easy to review
• Report blockers with concrete technical evidence

holon-reviewer

Pre-configured for code review:

• Inspect pull requests for correctness, regressions, and contract drift
• Prioritize concrete findings with clear severity and file references
• Distinguish proven issues from open questions

holon-release

Pre-configured for release work:

• Prepare release changesets, version bumps, and release notes
• Verify release prerequisites before publishing
• Surface irreversible steps before executing them

holon-github-solve

The most feature-rich template. Pre-configures the agent for GitHub workflows and pre-installs four skills for issue solving, PR fixing, code review, and GitHub CLI operations.

Using --template

Create an Agent

holon agent create reviewer --template holon-reviewer

This initializes ~/.holon/agents/reviewer/AGENTS.md with the reviewer role contract. 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
└── skills.json     # 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.

skills.json

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

{
  "skill_refs": [
    { "kind": "builtin", "name": "github-issue-solve" },
    { "kind": "builtin", "name": "github-pr-fix" },
    { "kind": "local", "path": "/path/to/custom-skill" }
  ]
}

Two skill reference kinds are supported:

• builtin — A skill shipped with Holon (e.g. ghx, github-issue-solve)
• local — An absolute path to a skill directory on disk

Creating Custom Templates

Create a directory with an AGENTS.md and optional skills.json, 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.