--- title: Manage forks and updates canonical: "https://agentbarn.dev/guides/templates-and-skills/forks-and-updates" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-13T13:41:42.000Z" author: Agent Barn description: Create Organization forks through drafts and adopt newer Platform snapshots with explicit Template Updates. tags: [Templates and Skills, Concept, "Template authors, Organization administrators, and Agent operators", Template fork, draft, Platform Update, restore, version baseline, Skill forks] categories: [Guides, Templates and Skills] --- - Templates and Skills - 10–12 minutes Organization forks let you customize a built-in Platform Template without changing the global template, or affecting other organizations. A fork remains connected to its Platform lineage through a recorded baseline. When a newer Platform version becomes available, Agent Barn can copy that version into the Organization fork as another immutable Organization version. **Core principle** A Platform update replaces the fork’s current snapshot with the latest complete Platform snapshot. It does not merge Platform changes with Organization customizations. ## Before you begin You need: - Access to the organization containing the template - `template.read` permission to view templates and version history - `template.manage` permission to create or update an Organization fork - Permission to update an agent when changing its selected template version - Lifecycle permission when applying a version to a running agent Organization Members can view and use shared templates. Organization Owners and Administrators can manage their definitions. Platform Template authoring requires separate Platform Administrator permissions. If you have not worked with immutable template versions, read [Manage template versions](/guides/templates-and-skills/template-versions) first. ## Understand the template sources Agent Barn distinguishes between several template sources. ### Built-in Platform Template Ownership Global platform Who can edit it Platform Administrators Update relationship Publishes global Platform versions ### Organization fork Ownership One organization Who can edit it Organization template managers Update relationship Tracks a Platform baseline ### Organization-owned template Ownership One organization Who can edit it Organization template managers Update relationship No Platform source ### Agent override Ownership One agent Who can edit it Users permitted to configure that agent Update relationship Tracks its direct shared source This guide focuses on Organization forks of Platform Templates. Organization-owned templates do not receive Platform updates, because they have no Platform source. Agent overrides have a separate Agent-owned version and draft model, covered in [Use Agent overrides](/guides/templates-and-skills/agent-overrides). ## How an Organization fork works Editing a built-in Platform Template creates an Organization-scoped fork. The fork: - Keeps the Platform Template’s stable template key - Copies its content into Organization version `1` - Copies its required Skill rules - Records the Platform version used as its baseline - Starts an independent Organization version sequence - Leaves the global Platform Template unchanged - Does not move existing agents **Platform Template: _key tpl-4f6a71b29c83_** - Platform v1 - Platform v2: baseline - Platform v3 **Organization fork: _created from Platform v2_** - Org v1 - Org v2 **Pinned agents: _each pin is independent_** - Agent A → Org v1 - Agent B → Org v2 The Organization sequence is independent of the Platform sequence. A fork created from Platform `v2` starts at Organization `v1`, not Organization `v3`. The same visible lineage can therefore contain: ``` Built-in platform v1 Built-in platform v2 Built-in platform v3 Organization fork v1 Organization fork v2 ``` **Important** Always check the source label as well as the version number. Built-in platform `v2` and Organization fork `v2` are different snapshots. ## Fork, baseline, and origin An Organization fork maintains two related ideas: - **Origin** identifies the Platform Template from which the fork was originally created. - **Baseline** identifies the latest Platform version explicitly adopted into the Organization fork. Suppose an organization creates a fork from Platform `v2`: ``` Origin: Platform Template tpl-4f6a71b29c83 Baseline: Platform v2 Current: Organization v1 ``` The organization then publishes two custom changes: ``` Origin: Platform Template tpl-4f6a71b29c83 Baseline: Platform v2 Current: Organization v3 ``` Publishing Organization changes does not advance the Platform baseline. If the organization later applies Platform `v5`, Agent Barn creates the next Organization version and advances the baseline: ``` Origin: Platform Template tpl-4f6a71b29c83 Baseline: Platform v5 Current: Organization v4 ``` The fork’s original lineage remains intact. ## Create an Organization fork To fork a Platform Template into an Organization, start a draft from the visible Platform version. Publishing creates Organization version 1 under the stable Template key and records the source baseline. The Organization's published version sequence is independent of the Platform sequence. Existing Agent pins do not move. Open Settings → Templates and the visible Platform lineage detail. Start a draft, edit and save it, then publish explicitly. ### How fork resolution changes An Organization fork uses the same stable template key as its Platform source. Once an Organization version exists, Organization-level template resolution prefers the Organization lineage for that key, so the fork represents the organization’s customized version of the built-in template. The Platform versions still exist and remain visible in version-selection interfaces. An agent can be explicitly pinned to either a Built-in Platform version or an Organization fork version. The exact source is stored with the agent’s template pin, so overlapping version numbers do not create ambiguity. ## Detect an available Platform update Agent Barn compares the latest Organization fork’s recorded baseline with the latest published Platform version. An update is available when the latest Platform version is higher than the fork’s Platform baseline. ``` Latest Platform version: v5 Fork Platform baseline: v3 Platform update: Available ``` The Templates list and template drawer display **Platform update available** when a newer Platform version can be adopted. The update status belongs to the fork lineage as a whole. Selecting an older Organization version in the history does not change whether the latest fork version has an update available. **Tip** A Platform update badge means the Platform lineage advanced. It does not mean the update has already been applied to the fork, or to any agent. ## Review an update before applying it A Platform update replaces the fork’s current content, so review it as a new release. 1. Record the current Organization version. 2. Record the current Platform baseline. 3. Open the latest Built-in Platform version. 4. Review its description. 5. Review all eight Markdown artifacts. 6. Review its required Skills and Skill groups. 7. Identify Organization-specific customizations in the current fork. 8. Decide which customizations must be reapplied afterward. 9. Identify one test agent for validation. The complete template snapshot includes `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, `AGENTS.md`, `BOOT.md`, `BOOTSTRAP.md`, `HEARTBEAT.md`, the description, and the required Skill rules. There is no partial Platform update. Agent Barn adopts the latest complete Platform snapshot. ## Apply a Platform update **Warning** Applying a Platform update replaces the fork’s Organization customizations with the latest Platform content and required Skills. It is not a merge operation, and it cannot be reversed in place; recovery means repinning agents to an earlier version, or publishing a new one. To apply the update: 1. Open your organization. 2. Go to **Templates**. 3. Select the Organization fork marked **Platform update available**. 4. Confirm the displayed Platform baseline. 5. Select **Apply platform update**. 6. Review the confirmation. 7. Select **Apply update**. 8. Note the new Organization version number. 9. Review the resulting version before applying it to an agent. If the current Organization version is `v3`, the update creates Organization `v4`. The new version contains the latest Platform description, all eight Markdown artifacts from the latest Platform version, the latest Platform required Skill rules, and the updated Platform baseline. The update does not modify Organization `v1`, `v2`, or `v3`. ## Replacement, not merge Consider a fork whose Organization version customized the escalation path, and a Platform version that then changed the same content. ### Platform v4: new source - Improved support instructions - New severity-based escalation - Required Skills: Jira and Slack ### Organization v2: current fork - Standard support instructions - Custom escalation to Team Atlas - Required Skill: Jira ### Organization v3: result - Improved support instructions - New severity-based escalation - Custom escalation to Team Atlas Not carried forward - Required Skills: Jira and Slack The custom Team Atlas escalation is not merged into Organization `v3`. If that customization is still needed, edit Organization `v3` and save it as Organization `v4` containing both the new Platform behavior and the local escalation rule. This makes the release sequence explicit, and preserves every intermediate snapshot. ## What happens to existing agents Applying a Platform update creates a template version. It does not update an agent’s selected version. ### Before the update ``` Agent A ── Organization v2 Agent B ── Organization v2 Agent C ── Platform v3 ``` ### After the update ``` Agent A ── Organization v2 Agent B ── Organization v2 Agent C ── Platform v3 Organization v3 is available but not yet selected. ``` This separation gives you time to test the updated fork. To roll out the update: 1. Select a test agent. 2. Apply the new Organization version. 3. Restart the agent if it is running. 4. Verify its health, activity, logs, and behavior. 5. Apply the version to a small production group. 6. Monitor the group. 7. Move the remaining agents when ready. There is no automatic fleet-wide rollout. ## Reapply Organization customizations When the Platform snapshot is correct but your organization still needs local changes: 1. Apply the Platform update. 2. Open the newly created Organization version. 3. Select **Start draft**. 4. Reapply the required Organization-specific content. 5. Review the required Skills. 6. Save the draft, then publish it explicitly. 7. Test the resulting Organization version. This creates one version for the adopted Platform snapshot, and another for the Organization customization: 1. **Org v3** Previous customized fork 2. **Org v4** Exact Platform snapshot, created by the Platform update 3. **Org v5** Updated customized fork, after reapplying Organization changes This history makes it clear which Platform content was adopted, and which changes were added by the organization. ## Required Skills during an update A Platform update copies the latest Platform version’s complete required Skill configuration. That includes standalone Skills that are all required, and Skill groups where at least one member must be assigned. The fork’s previous Skill requirements are replaced. Before applying the new Organization version to an agent: 1. Inspect its required Skills. 2. Confirm that the required Skills are visible to the organization. 3. Confirm that the agent has the required standalone Skills. 4. Choose at least one Skill from every required group. 5. Configure any required provider credentials. 6. Apply the template version. Agent Barn validates the exact selected version’s requirements when the agent is updated. An agent still pinned to the older Organization version remains governed by that older version’s requirements. ## Apply an update with the API Use the Organization Template update endpoint. No request body is required. ``` POST /api/v1/organizations/{organization_id}/templates/{template_key}/platform-update ``` Example: ``` curl --request POST \ --url "${AGENT_BARN_URL}/api/v1/organizations/${ORGANIZATION_ID}/templates/${TEMPLATE_KEY}/platform-update" \ --header "Authorization: Bearer ${AGENT_BARN_TOKEN}" ``` A successful request returns `201 Created` and the newly created Organization version: ``` { "template_key": "tpl-4f6a71b29c83", "template_name": "Customer Support Agent", "template_source": "pre-defined", "version": 4, "fork_baseline_platform_version": 5, "platform_update_available": false } ``` The response also contains the copied template content and required Skills. **Permissions** Applying a Platform update requires the Organization permission `template.manage`. ### Platform update validation The API rejects the update when: - The template key does not identify an Organization fork - The template is an Organization-owned custom template - The fork’s Platform baseline is unavailable - No newer Platform version exists - The caller lacks `template.manage` permission Possible conflict responses include: ``` 409 Template Update is only available for organization forks of Platform Templates 409 No newer Platform Template Version is available 409 The fork's Platform Template baseline is no longer available ``` Refresh the template before retrying, so you are working with its latest lineage state. ## Choose the correct action | Goal | Correct action | | --- | --- | | Customize a built-in for the organization | Edit the Built-in template to create an Organization fork | | Change an existing Organization fork | Edit it and publish the next Organization version | | Adopt the latest Platform snapshot | Apply the Platform update | | Keep local changes while adopting Platform changes | Apply the update, then reapply local changes in another Organization version | | Test the latest Platform version without changing the fork | Pin a test agent directly to that Platform version | | Move one agent to the updated fork | Apply the exact Organization version to that agent | | Undo an agent rollout | Repin the agent to its previous version | | Make previous fork content latest again | Publish the historical content as the next Organization version | | Give one agent private changes | Create an Agent override | | Permanently combine Platform and Organization changes automatically | Not supported; review and reapply changes explicitly | ## Use a safe update workflow A recommended release sequence is: 1. Platform update detected 2. Review latest snapshot 3. Record customizations 4. Apply update 5. Reapply customizations 6. Test with one Agent 7. Canary rollout 8. Wider rollout For high-impact templates, keep the previous Organization version pinned to at least one test agent until the new version has been verified. ## Roll back after a Platform update Because previous Organization versions remain immutable, you have two rollback options. ### Roll back one agent Repin the agent to its previous Organization version. This is the fastest option, and it does not create a template version. ``` Agent A: Organization v5 → Organization v3 ``` Other agents remain unchanged. ### Restore fork content as a new version If historical content must become the latest fork version: 1. Open the historical Organization version. 2. Review all artifacts and required Skills. 3. Edit or reproduce its complete snapshot. 4. Save it as the next Organization version. 5. Apply the new version to the required agents. This preserves the Platform update in history, while creating a new immutable version containing the restored behavior. For an exact API restoration, submit all template fields and Skill requirements. Omitted fields inherit from the current latest Organization version. ## Return an agent to the Platform source Creating a fork does not prevent an individual agent from using a Built-in Platform version. 1. Open the agent. 2. Go to **Configuration**. 3. Open the template selector. 4. Find the entry labeled **Built-in platform**. 5. Select the exact Platform version. 6. Preview its content and required Skills. 7. Select **Apply** or **Apply & Restart**. This changes only that agent’s pin. It does not remove or alter the Organization fork. ## Deleting and detaching forks Organization forks cannot be deleted through normal Template deletion. You also cannot detach a fork and convert its existing lineage into a normal Organization-owned template. If you need a separately managed template with no Platform update relationship: 1. Create a new Organization-owned template. 2. Copy the desired content. 3. Configure its required Skills. 4. Publish it as Organization version `1`. 5. Test it. 6. Move the required agents to the new template. The original Organization fork remains available with its history and Platform relationship. ## Template forks and Skill forks are different | Template fork | Skill fork | | --- | --- | | Organization snapshot of a Platform Template | Independent Organization or Agent Skill lineage | | Tracks a Platform Template baseline | Tracks an exact direct-source Skill Version | | Publishes Organization Template Versions | Begins with an unpublished Skill Draft | | Template Update creates the next Organization version | Apply Update publishes immediately or replaces an existing draft | | Replaces the complete Organization Template snapshot | Replaces complete Skill files and source-derived metadata | | Existing Agent Template pins do not move | Existing Agent and Template Skill pins do not move | Templates and Skills do not share one generic fork implementation. Template updates use the Platform Template baseline described above. Skill forks have their own scoped lineage, exact direct-source provenance, and draft behavior. ## Fork Skills through the scope hierarchy ``` Platform Skill ├── Organization fork └── Agent-private fork Organization Skill └── Agent-private fork ``` Supported directions are Platform Skill to Organization Skill, Platform Skill to Agent-private Skill, and Organization Skill to Agent-private Skill. The reverse directions are unsupported, as are one Agent’s private Skill to another Agent. Platform is the root scope and has no Platform fork action. An Organization sees a Platform Skill as read-only and forks it rather than editing it in place. An Agent may fork a visible Platform or Organization Skill into that Agent’s private scope; another Agent’s private Skill is never visible as a source. ## Create a Skill fork 1. Resolve the selected source Skill’s latest published version. 2. Create an independent lineage in the destination scope. 3. Copy the complete source file tree, description, and required provider metadata. 4. Record the exact source Skill ID and source version. 5. Create one unpublished draft and no published version. 6. Review or modify the draft, then publish it to create fork version `1`. The fork owns its stable identity, name, immutable slug, mount directory, scope, draft, versions, file snapshots, provider requirements, and future source-update state. Forking source version `7` still begins with an unpublished fork whose first publication is fork version `1`. ``` Platform Skill: Incident response v4 ↓ fork Organization Skill: Incident response Draft source: Platform Skill v4 ↓ publish Organization Skill v1 Published source: Platform Skill v4 Organization Skill v1 ↓ fork Agent-private Skill draft Direct source: Organization Skill v1 ``` Direct-source updates are not transitive: an Agent-private fork of Organization Skill `v1` follows that Organization lineage, not the original Platform Skill behind it. Changes never mutate the source, and source changes never mutate the fork automatically. ## Detect a direct Skill source update A Skill fork has an update available when its direct source lineage has a newer published version than the source version recorded by the fork’s current draft or latest published version. Availability is based on persisted direct-source provenance, not display name, slug, file comparison, an indirect upstream source, an Agent pin, or whether local files changed. **Important** Exact provenance is an operational reference. A source Skill Version or lineage cannot be deleted while a fork draft or published fork version still records it as source. ## Apply a Skill source update ### No mutable draft Apply Update resolves the newest direct-source version, copies its files, description, provider requirements, and exact provenance, then immediately publishes the copied snapshot as the fork’s next immutable version. The fork finishes with no draft; existing consumers remain pinned. ``` Organization fork v2 Source baseline: Platform Skill v4 No draft exists Platform Skill v5 becomes available Apply Update ↓ Organization fork v3 is published Source baseline: Platform Skill v5 ``` ### Existing mutable draft **Unpublished local edits will be replaced** Apply Update replaces, rather than merges, the current draft’s files, description, provider requirements, and direct-source provenance. Review or copy local edits before confirming. The replacement draft remains unpublished for review and may be edited before publication. Its next immutable version records the exact source snapshot used as baseline, even if later local edits make it no longer byte-for-byte identical. ``` Organization fork v2 Unpublished local draft exists Platform Skill v5 becomes available Apply Update ↓ Draft contents are replaced by Platform Skill v5 Draft remains unpublished Organization fork v2 remains the latest published version ``` Later source updates replace from the newest direct source again; Agent Barn does not perform a three-way merge or preserve conflicting local draft edits automatically. ## Adopt a Skill update explicitly Applying a source update affects only the fork lineage. It never automatically updates Agent Skill pins, Platform or Organization Template Skill requirements, Agent Template Override requirements, or Runtime-mounted files. Consumers adopt a newer published fork version only after explicit selection; a replaced draft cannot be adopted until it is published. | Resource | Draft exists? | Apply Update result | Consumer pins | | --- | --- | --- | --- | | Organization Skill fork | No | Publishes the next Organization Skill Version immediately | Unchanged | | Organization Skill fork | Yes | Replaces the draft and leaves it unpublished | Unchanged | | Agent-private Skill fork | No | Publishes the next Agent-private Skill Version immediately | Unchanged | | Agent-private Skill fork | Yes | Replaces the draft and leaves it unpublished | Unchanged | | Organization Template fork | Not the same draft contract | Creates the next complete Organization Template Version | Unchanged | ## Use scoped permission and API boundaries Creating an Organization fork requires `skill.manage`; users with `skill.read` can inspect visible Platform and Organization Skills but cannot create, update, publish, or delete forks. Agent-private forks require access to the owning Agent and its corresponding Agent mutation permission. Platform Administrators manage Platform Skills directly. ``` POST /api/v1/organizations/{organization_id}/skills/{source_skill_id}/fork POST /api/v1/organizations/{organization_id}/skills/{skill_id}/source-update POST /api/v1/organizations/{organization_id}/agents/{agent_id}/skills/{source_skill_id}/fork POST /api/v1/organizations/{organization_id}/agents/{agent_id}/skills/{skill_id}/source-update ``` There are no Platform fork or Platform source-update routes. ## Keep Agent Override updates separate An Agent Template Override source update uses the Override’s direct Platform or Organization Template source and selects the complete newer shared Template snapshot for that Agent. It does not mutate an Override Draft or publish an Override Version; it follows the existing Apply and Restart workflow. See [Use Agent Overrides](/guides/templates-and-skills/agent-overrides) for the full contract. ## Troubleshooting ### The Platform update badge does not appear Only forks track a Platform baseline Check that: - The template is an Organization fork. - Its source is a Built-in Platform Template. - A Platform version newer than the fork’s baseline has been published. - You are viewing the latest state of the fork. - The page has been refreshed. Organization-owned templates do not receive Platform update notifications. ### Selecting an older fork version changes the displayed baseline but not the update button Update status follows the latest version Historical versions retain the baseline recorded when they were published. The update-available result, however, is determined from the latest Organization version for the lineage. Selecting an old version does not change the current update status. ### Applying the update removed our custom instructions Expected: replacement, not merge This is expected. Platform updates copy the complete latest Platform snapshot and replace Organization customizations. Repin affected agents to the previous Organization version, then reapply the customizations in a new version. ### Applying the update did not change any agents Publication and selection are separate Template publication and Agent selection are separate operations. Apply the new Organization version to each intended agent. Restart running agents so they load the new runtime configuration. ### I receive “No newer Platform Template Version is available” The baseline is already current The fork’s baseline is already at the latest Platform version, or another user applied the update before your request completed. Refresh the template and inspect its current baseline. ### I receive “Template Update is only available for organization forks” The lineage is not a fork The selected template is likely a Built-in Platform Template that has not been forked, an Organization-owned custom template, or a lineage that is not recorded as a Platform fork. Only Organization forks can use the Platform update endpoint. ### The latest Platform version adds required Skills Configure them before applying Configure those Skills and any required provider credentials before applying the new Organization version to an agent. Existing agents pinned to an older version remain unchanged. ### I want to adopt an intermediate Platform version The update adopts the latest snapshot The Platform update action adopts the latest published Platform snapshot. It does not let the fork choose an intermediate Platform baseline. You can test an older Platform version by pinning an agent directly to that exact Platform version. If the fork must incorporate selected historical content, reproduce it deliberately as a new Organization version, and review every artifact and Skill requirement. ### I cannot delete the Organization fork Forks are protected from deletion Organization forks are protected from normal Template deletion. Create a separate Organization-owned template if you need an independent lineage, then move agents explicitly. ## Recommended practices - Record the fork’s Platform baseline before making Organization changes - Keep Organization customizations focused and documented - Review all eight artifacts before applying an update - Treat required Skill changes as part of the release - Assume an update is a replacement, never a merge - Test updates with a dedicated agent - Use a canary rollout before moving all agents - Keep previous versions available for rollback - Reapply local changes as a separate immutable version - Record both source and version when discussing a template - Never assume publishing or updating automatically moves agents ## Next steps Continue to [Use Agent overrides](/guides/templates-and-skills/agent-overrides) to learn how one agent can maintain private template changes without modifying its Organization or Platform source. - [Work with Skills](/guides/templates-and-skills/skills) and [Manage Skill Versions](/guides/templates-and-skills/skill-versions) - [Skill scopes and Template concepts](/guides/templates-versions-and-skills) - [Manage template versions](/guides/templates-and-skills/template-versions) - [Work with templates](/guides/templates-and-skills/templates) - [Configure an Agent](/guides/agents/configuration) ## Template drafts and Platform Updates | Endpoint | Behavior | | --- | --- | | `POST /api/v1/organizations/{organization_id}/templates` | Create a new unpublished Template draft | | `GET /api/v1/organizations/{organization_id}/templates/lineages` | List lineage summaries, including draft-only lineages | | `GET /api/v1/organizations/{organization_id}/templates/{template_key}/versions` | Read published lineage versions | | `GET /api/v1/organizations/{organization_id}/templates/{template_key}/draft` | Read the current draft | | `POST /api/v1/organizations/{organization_id}/templates/{template_key}/draft` | Start or continue a draft | | `POST /api/v1/organizations/{organization_id}/templates/{template_key}/draft?source_version=2` | Seed a draft from the selected published version | | `PATCH /api/v1/organizations/{organization_id}/templates/{template_key}/draft` | Edit the unpublished draft | | `DELETE /api/v1/organizations/{organization_id}/templates/{template_key}/draft` | Discard the draft | | `POST /api/v1/organizations/{organization_id}/templates/{template_key}/draft/publish` | Publish the next immutable version | | `POST /api/v1/organizations/{organization_id}/templates/{template_key}/platform-update` | Apply the separate Platform Update operation | Direct `PATCH /{template_key}` is no longer the Template content-update endpoint. Save changes through the draft endpoint, then publish explicitly. To restore historical content, choose the intended published version and use the restore-as-draft action. Review or edit that draft, then publish it as the next version. The historical version remains unchanged. An existing draft must be discarded before restoring a different published source; an explicit source selection conflicts while a draft already exists. A Platform Update is separate from ordinary authoring. It copies a newer complete Platform snapshot into the next Organization version, replacing Organization customizations rather than merging them. It advances the recorded baseline and leaves Agent pins unchanged. Do not treat every Template operation as a draft save, and do not describe an update as automatic propagation to Agents.