Work with templates

Open the Template catalog

In Agent Barn:

1. Open the intended Organization.
2. Open Settings.
3. Select Templates.

Organization → Settings → Templates

The catalog displays the latest visible version from global built-in Platform Templates, custom Organization Templates, and Organization forks.

Start a new Organization Template

If you are an Organization Owner or Admin:

1. Select New template.
2. Enter a stable Template name.
3. Add a short description.
4. Define required Skills if needed.
5. Author the visible Markdown artifacts.
6. Select Create template.

Creating an Organization Template immediately publishes version 1. The Organization workflow does not create an unpublished shared draft.

Template: Customer Support
Key:      tpl-a1b2c3d4e5f6
Version:  v1
Source:   Custom

The Template name cannot be changed after creation. Choose a name that describes the reusable role rather than one specific Agent.

Recommended authoring sequence

1. Define the behavioral boundary in SOUL.md and the role in IDENTITY.md.
2. Add repeatable workflows to AGENTS.md.
3. Add tool-selection conventions to TOOLS.md.
4. Provide a context schema in USER.md.
5. Route triggers in BOOT.md.
6. Add idempotent preparation to BOOTSTRAP.md.
7. Add bounded proactive checks to HEARTBEAT.md.

Before writing workflows, establish what the Agent is, what it is allowed to do, what it must never do, what authority it lacks, when it must ask for confirmation, and when it must escalate.

Add repeatable workflows

A useful workflow includes a trigger, required inputs, validation, ordered actions, an approval boundary, expected output, failure or escalation behavior, and the durable state that should be recorded.

Avoid relying on vague instructions:

Handle support tickets appropriately.

Prefer an explicit contract:

For a support request:

1. Classify it as informational, access-related, billing-related, or technical.
2. Answer informational requests from approved documentation.
3. Never perform an account or billing change without the required authority.
4. Escalate security incidents immediately.
5. End with the action taken or the next owner.

Keep content in the correct artifact

Write for reuse

A shared Template should avoid hardcoding a specific Agent name, a platform bot username, one Slack channel, one Telegram chat ID, one Discord server, one person’s credentials, one customer’s private information, or environment URLs that are supplied by an integration.

Use supported placeholders for the Agent name, and let Agent configuration provide platform routing and credentials.

A Template can require explicit Skill assignments.

Required:
- Jira
- Confluence

Agent must have:
Jira AND Confluence

Code host:
- GitHub
- Bitbucket

Agent must have:
GitHub OR Bitbucket

A Skill cannot simultaneously be a standalone requirement and a member of a group, and it cannot belong to more than one requirement group in the same Template version.

Add required Skills

In the Template editor:

1. Find Required skills.
2. Search for an accessible Skill.
3. Select Add for a standalone requirement.
4. To create an alternative group, select Group skills.
5. Select the alternatives.
6. Choose Group as “at least one of”.
7. Review the required providers shown under each Skill.

Provider requirements

A required Skill may need a provider credential.

Template requires:
At least one of GitHub or Bitbucket

Agent selects:
GitHub

Agent must also have:
A valid GitHub Agent Secret or Shared Credential

Agent Barn validates required Skills and provider credentials when an Agent is hired, updated, or repinned.

The Template references the Skill lineage, not a specific Skill version. When the Skill is assigned to an Agent, that Agent pins an exact Skill version.

Select a Template while hiring

1. Select a Template.
2. Select the intended published version.
3. Review its description.
4. Preview the Markdown artifacts.
5. Review standalone and grouped Skill requirements.
6. Assign the required Skills.
7. Supply required provider credentials.
8. Finish creating the Agent.

The Agent pins the selected version. A later Template publish does not move that pin.

Apply a Template to an existing Agent

Agent → Configuration → Template

1. Select Edit.
2. Search by Template name, version, or key.
3. Select an exact published version.
4. Preview the selected snapshot.
5. Review required Skills.
6. Add missing required Skills in the Agent’s Skills section if necessary.
7. Apply the selection.

Preview the selected version before applying it. Agent Barn revalidates required Skills during selection, and the apply action is blocked if the Agent lacks a standalone requirement, or every member of a required-Skill group.

Open the Template from Organization → Settings → Templates, then:

1. Select the version you want to inspect.
2. Select Edit template.
3. Update the description, artifacts, or required Skills.
4. Select Save.

Saving publishes the next immutable Organization version:

v1 ── existing immutable snapshot
v2 ── newly saved immutable snapshot

This is not an in-place edit. The Template name and key remain unchanged, and existing Agents remain pinned to their current versions.

If an update request omits an artifact or required-Skill collection through the API, Agent Barn inherits that content from the prior version.

Verify the new version with a test Agent before moving production Agents to it.

To customize a built-in Platform Template:

1. Open Organization → Settings → Templates.
2. Filter by Built-in if needed.
3. Open the Platform Template.
4. Select Edit template.
5. Change the Organization-specific behavior.
6. Select Save.

Editing a built-in creates an Organization fork:

1. Platform Template v4 The global built-in the Organization starts from
2. Organization fork v1 The first Organization-owned snapshot, always version 1
3. Organization v2, v3 Further Organization versions, evolving independently

The first Organization snapshot is always Organization version 1, regardless of the Platform version it was forked from. The fork keeps the stable Template key, its Platform origin, the Platform baseline version, and a separate Organization version sequence.

Existing Agents stay on their exact prior pins. They do not automatically move to the new fork.

Apply a Platform Template update

When a newer Platform version is available, Agent Barn displays Platform update available. Selecting Apply platform update creates the next Organization version from the complete newer Platform snapshot.

Before applying:

1. Review the current Organization customization.
2. Review the newer Platform version.
3. Save any changes that must be reintroduced.
4. Apply the Platform update.
5. Create another Organization version if local behavior must be added again.
6. Test before repinning Agents.

Existing Agent pins remain unchanged after the Platform update.

Built-in Platform Templates and their Organization forks cannot be deleted through normal Organization Template deletion.