Templates and Skills

On this page

Before you begin
How template versioning works
Latest does not mean active
Understand the version sources
1. View version history
2. Publish a new version
Choose the correct action
Test and release a version
3. Apply a version to an agent
4. Roll back one agent
5. Republish historical content
Restore a Platform version
Required Skills across versions
Placeholders and rendering
Update a fork from Platform
Delete template versions
API reference
Troubleshooting
Operating practices
Next steps

Templates and Skills
12–15 minutes

Template versions let you improve an agent definition without changing the configuration of agents that already use it.

Every published version is an immutable snapshot. Publishing a change creates another version instead of modifying the existing one, and each agent remains pinned to its selected version until someone explicitly moves it.

Before you begin

You need:

Access to the organization containing the template
template.read permission to inspect templates and their history
template.manage permission to publish Organization Template versions
Permission to update an agent when changing its selected version
Lifecycle permission when applying a version to a running agent

Platform Templates require separate Platform Administrator permissions.

This guide assumes that you already understand how to create and edit templates. If not, begin with Work with templates.

How template versioning works

A template lineage has a stable template key, such as tpl-4f6a71b29c83. The key identifies the template across its published versions, and the template name and key remain stable while the version number increases.

Each version is a complete snapshot containing the description, all eight Markdown artifacts, and the required Skill rules:

Description
SOUL.md
IDENTITY.md
USER.md
TOOLS.md
AGENTS.md
BOOT.md
BOOTSTRAP.md
HEARTBEAT.md
Required Skill rules

Versions are immutable, and agents pin them independently:

v1 Initial published snapshot
- Agent A
- Agent C
v2 Revised escalation behavior
- Agent B
v3 Latest published version
- New agents, when no version is specified

You cannot overwrite v2 after it has been published. A new change becomes v4.

Latest does not mean active

A template does not have one globally active version.

“Latest” means the highest published version available in a particular template lineage and source. “Active” refers to the exact version currently selected by an individual agent.

Agent	Selected version	Latest version	Status
Support East	`v2`	`v4`	Update available
Support West	`v4`	`v4`	Latest
Support Test	`v3`	`v4`	Update available

This lets you test a version with one agent before applying it to others.

Understand the version sources

Agent Barn can show versions from several sources. Their version numbers are independent sequences.

Platform Template

Organization fork — created from Platform v3

Org v1
Org v2
Org v3

Agent Override — created from Organization v3

Source	Scope	Version sequence
Built-in platform	Available globally	Platform-managed
Organization-owned	Available within one organization	Organization-managed
Organization fork	Organization copy of a Platform Template	Independent Organization sequence
Agent override	Available only to one agent	Independent Agent sequence

An Organization fork created from Platform v3 starts at Organization v1. It does not become Platform v4.

View version history

To inspect a template’s history:

Open your organization.
Go to Templates.
Select the template.
Open the version selector or history view.
Select a version to preview its artifacts and required Skills.

The newest versions appear first. Before applying a version, review:

Its source
Its version number
Its description
Each Markdown artifact
Required standalone Skills
Required Skill groups
Whether the agent already uses that version
Whether a newer Platform or Organization version is available

Publish a new Organization version

Organization Templates do not use a shared draft. Saving a change immediately publishes the next immutable Organization version.

Open the Organization Template.
Select Edit template.
Change the required artifacts, description, or Skill requirements.
Review the complete template.
Select Save.

If the latest version was v3, the saved template becomes v4. The previous versions remain available, and agents using them remain unchanged.

Partial API updates

When the API is used to publish an Organization version, omitted fields inherit their values from the latest Organization version.

PATCH /api/v1/organizations/{organization_id}/templates/{template_key}
Content-Type: application/json

{
  "description": "Improve escalation behavior for urgent requests.",
  "agents_md": "# AGENTS.md\n\nEscalate urgent requests to the on-call operator."
}

A successful update creates the next version:

{
  "template_key": "tpl-4f6a71b29c83",
  "template_name": "Customer Support Agent",
  "version": 4
}

It does not modify version 3.

Choose the correct version action

Different actions have different effects.

Action	Creates a version?	Moves an agent?	Changes previous history?
Publish an Organization change	Yes	No	No
Apply a version to one agent	No	Yes	No
Roll back one agent	No	Yes	No
Republish historical content	Yes	No	No
Apply a Platform update to a fork	Yes	No	No
Delete a custom template lineage	No	Not allowed while in use	Deletes its complete history

Use Apply when you want one agent to use an existing version. Publish a new version when you want to create a new reusable snapshot.

Test and release a new version

Treat template changes like application releases.

Publish next version Saving an Organization Template publishes the next immutable version
Apply to a stopped test agent Nothing moves until you apply it
Verify Skills and credentials The exact version being applied is validated
Start the agent and run a test conversation Exercise representative tasks
Review health, activity, and logs Confirm the behavior change and look for regressions
Apply to a small group of agents Monitor the canary group
Roll out to the remaining agents Each agent moves only when you apply the version

Recommended steps:

Publish the next template version.
Preview the complete snapshot.
Confirm that its required Skills are installed.
Apply it to a stopped test agent.
Start the agent.
Run representative conversations or tasks.
Review agent health and logs.
Apply it to a small set of production agents.
Monitor the canary agents.
Roll it out to the remaining agents.

There is no automatic rollout when a version is published.

Apply a version to an agent

To move an agent to another published version:

Open the agent.
Go to Configuration.
Open the template selection interface.
Find the required template and source.
Select the exact version.
Preview its artifacts and required Skills.
Select Apply or Apply & Restart.

For a stopped agent, Apply changes the pinned version and leaves the agent stopped. For a running agent, Apply & Restart stops the agent, changes its selected version, and starts it again.

Apply a version with the API

The selection request identifies both the source and exact version:

POST /api/v1/organizations/{organization_id}/agents/{agent_id}/configuration/select
Content-Type: application/json

{
  "selection_type": "organization",
  "template_key": "tpl-4f6a71b29c83",
  "template_version": 4,
  "expected_agent_updated_at": "2026-08-29T09:40:12Z"
}

Valid selection types include platform, organization, and override. The explicit selection type prevents ambiguity when Platform and Organization sources have the same template key and version number.

The expected_agent_updated_at value provides optimistic concurrency protection. If another user changed the agent after you loaded it, refresh the agent and retry with its current timestamp.

Roll back one agent

Rolling back an agent does not create another template version. It changes the agent’s pin to a previously published snapshot.

Open the affected agent.
Go to Configuration.
Open the template selector.
Select the previous source and version.
Preview the complete snapshot.
Confirm that its required Skills remain available.
Select Apply or Apply & Restart.
Verify the agent after it starts.

Only the selected agent moves. Other agents remain on their existing versions.

Before rollback

Agent A ── v4
Agent B ── v4
Agent C ── v3

After rolling back Agent A

Agent A ── v3
Agent B ── v4
Agent C ── v3

This is the fastest way to reverse a problematic rollout, because it reuses an existing immutable snapshot.

Make historical content the latest version

Sometimes you want historical content to become the latest reusable Organization version. Do not edit the historical version — publish another version containing the desired content.

If the current history is:

v1 ── v2 ── v3 ── v4
      desired       latest

Republishing the v2 content produces:

v1 ── v2 ── v3 ── v4 ── v5
      desired             restored content

Version v2 and version v4 remain unchanged.

From the Organization interface

Open the template history.
Select the historical version.
Preview its artifacts and required Skills.
Select Edit template.
Review every field.
Save it as the next Organization version.

Review USER.md carefully when reproducing an older snapshot. If the current editor does not expose that artifact, use the API for an exact full-snapshot restoration.

With the API

For an exact restoration, submit all eight Markdown artifacts, the description, and the required Skill rules. Do not omit fields: omitted fields inherit from the current latest version, not from the historical version you are restoring.

{
  "description": "Restored behavior from Organization v2.",
  "soul_md": "...",
  "identity_md": "...",
  "user_md": "...",
  "tools_md": "...",
  "agents_md": "...",
  "boot_md": "...",
  "bootstrap_md": "...",
  "heartbeat_md": "...",
  "required_skill_ids": [],
  "required_skill_groups": []
}

Publishing restored content still does not move existing agents. Apply the new version separately.

Restore a Platform Template version

Platform Templates use a Platform Administrator draft-and-publish workflow.

A Platform Administrator can:

Open the Platform Template’s version history.
Select a historical version.
Choose Restore vN as draft.
Review or edit the draft.
Publish the draft.

Publishing creates the next Platform version. It never changes or removes the historical versions. For example, restoring Platform v2 when v5 is current creates Platform v6.

Manage required Skills across versions

Required Skill rules belong to the individual template version. A newer version can:

Add a required Skill
Remove a required Skill
Change an “at least one of” Skill group
Keep the same artifacts but change its Skill requirements

Agent Barn validates the requirements of the exact version being applied. An agent pinned to an older version remains subject to that older version’s requirements until it is moved.

Before applying a version:

Inspect its required Skills.
Confirm that the organization has access to them.
Confirm that required provider credentials are configured.
Resolve missing requirements.
Apply the version.

The Apply action is blocked when the selected version’s required Skills are unavailable.

Understand placeholders and runtime rendering

Template placeholders are resolved when an agent starts, not when the template is published.

That means two agents can use the same immutable template version while receiving different rendered values, based on their names, organization details, or start context. The stored template version remains unchanged.

When you apply a version to a running agent, restart it so Agent Barn can render and generate its new runtime configuration.

Update an Organization fork from Platform

A Platform update is different from publishing a normal Organization edit. Applying a Platform update to an Organization fork:

Copies the latest complete Platform snapshot
Copies its required Skill rules
Creates the next Organization version
Replaces the fork’s Organization customizations
Advances the fork’s Platform baseline
Leaves all existing agent pins unchanged

It is a replacement operation, not a three-way merge.

POST /api/v1/organizations/{organization_id}/templates/{template_key}/platform-update

See Manage forks and updates for the complete workflow.

Delete template versions

Individual versions of a shared Platform or Organization Template cannot be deleted.

For an Organization-owned custom template, you can delete the entire lineage only when no live agent uses it:

DELETE /api/v1/organizations/{organization_id}/templates/{template_key}

Deleting the lineage permanently removes all of its versions.

You cannot delete:

One individual shared-template version
A built-in Platform Template
An Organization fork
A custom lineage still used by a non-deleted agent

Publishing a new version is allowed while older versions are in use. Live use blocks deletion of the lineage, not version creation.

API reference

List template versions

GET /api/v1/organizations/{organization_id}/templates/{template_key}/versions

The response is ordered newest first, and may include both Platform and Organization entries for a visible lineage. Check fields such as:

version
organization_id
template_source
forked_from_platform_template_id
fork_baseline_platform_version
Creation and update timestamps

Do not identify a version using its number alone.

Publish an Organization version

PATCH /api/v1/organizations/{organization_id}/templates/{template_key}

Omitted fields inherit from the current latest Organization version.

Apply a version to an agent

POST /api/v1/organizations/{organization_id}/agents/{agent_id}/configuration/select

Example request:

{
  "selection_type": "platform",
  "template_key": "tpl-4f6a71b29c83",
  "template_version": 5,
  "expected_agent_updated_at": "2026-08-29T09:40:12Z"
}

Apply the latest Platform snapshot to a fork

POST /api/v1/organizations/{organization_id}/templates/{template_key}/platform-update

This creates the next Organization version, but does not repin agents.

Troubleshooting

I published a version, but my agent still uses the old content

Expected: publishing never repins

Publishing does not move existing agents. Open the agent’s configuration and apply the new version.

Restart the agent if it is currently running.

Two entries have the same version number

Sequences are independent

They may come from different sources. Check whether each entry is a Built-in platform version, Organization-owned version, Organization fork, or Agent override.

Version sequences are independent.

Apply is blocked by missing Skills

The exact version is validated

The selected version requires Skills that are not available to the organization. Install or configure the required Skills, then retry.

The agent changed while I was applying a version

Optimistic concurrency

The optimistic concurrency check rejected a stale request. Refresh the agent, review the latest configuration, and retry using its current updated_at value.

I cannot apply a version through the API

The agent must be stopped

The agent must be stopped before the selection request. Stop it, apply the version, and start it again.

In the web interface, use Apply & Restart when that action is available.

I cannot delete an old version

Shared versions are immutable

Shared-template versions are immutable and cannot be individually deleted. Old versions remain available for auditing and rollback.

You can delete an entire Organization-owned custom lineage only when no live agent uses it.

Restoring historical content produced a mixed snapshot

Omitted fields inherit from latest

A partial Organization update inherits omitted fields from the current latest version. To reproduce a historical version exactly, submit all eight artifacts, its description, and its complete required Skill rules.

My Organization fork lost its custom changes

Platform update replaces the snapshot

Applying a Platform update replaces the Organization fork snapshot; it does not merge customizations.

Select an older Organization version to recover an agent, or publish another Organization version containing the required customizations.

Recommended operating practices

Treat every version as a release artifact
Use descriptions that explain the behavioral change
Test new versions with a dedicated agent
Roll out to a small canary group first
Review required Skills before applying a version
Record both the version number and its source
Keep agents pinned until their update is intentional
Roll back by selecting a known-good version
Republish historical content only when it must become the new latest version
Review Organization customizations before applying Platform updates

Next steps

Continue to Manage forks and updates to learn how Organization forks track Platform changes, and how to safely adopt a new Platform snapshot.