Templates, Versions, Overrides, and Skills

New Organization Templates begin as draft-only lineages. They become selectable as published Templates after their first publication. Organization Members can read and use published Templates but cannot author shared definitions. Organization Owner/Admin manage Organization Templates; Platform authoring requires Platform Administrator authority.

New Organization Templates begin as draft-only lineages. Open Settings → Templates, use the dedicated lineage detail/editor, save unpublished work, then publish and explicitly repin each Agent that should adopt it.

An Agent uses one exact published version from one of three sources: a Platform Template when a shared platform Template fits, an Organization Template when your Organization maintains its own, or an Agent Template Override when you need to customize one Agent without changing a shared Template or another Agent.

An Agent Template Override contains a complete snapshot of the Template configuration. It is not a set of changes that automatically follows the shared Template. The Override belongs to one Agent, and other Agents cannot select it even when they belong to the same Organization. See /guides/templates-and-skills/agent-overrides for the editing workflow.

Skills have Platform, Organization, and Agent scopes. Skill visibility is additive: an Agent can see Platform Skills, its Organization’s Skills, and its own private Skills, but not another Organization’s Skills or another Agent’s private Skills. Platform Administrators manage Platform Skills, Organization managers manage Organization-owned Skills, and Agent-private Skills are managed through Agent-scoped routes and Agent Access authority.

Platform Skill: global Platform resource, visible across Organizations.

Organization Skill: owned by one Organization, visible within that Organization.

Agent-private Skill: owned by one Organization and Agent, visible only through that Agent.

A new Skill or Skill fork begins with one mutable draft and no published version. Publishing copies the draft’s complete file tree and staged metadata into the next immutable Skill Version, then clears the draft.

An Agent pins one exact active Platform Template, Organization Template, or Agent Template Override Version and every assigned Skill stores an exact pinned Skill Version. Template and Override requirements store both Skill identity and exact required version. Publishing a newer Template, Override, or Skill Version never changes an existing pin; consumers adopt one only through explicit apply, repin, or source update. Recover a bad Skill Version by explicitly re-pinning an older valid version, never by mutating published history.

Publishing and applying are separate steps. Publishing makes a version available for selection; it does not change what an Agent currently uses. For a stopped Agent, select Apply and the Agent loads the selection when you next start it. For a running Agent, use Apply & Restart: the Runtime stops, the selection changes, and the Agent starts again.

An unpublished Override draft cannot be applied. Selecting another published version does not discard an existing Override draft. Publishing a newer Skill Version likewise does not update existing Agent Skill assignments or Template requirements, which keep their selected versions until explicitly changed.

Draft: mutable authoring state, never used directly by a Runtime.

Published version: immutable, used when exactly pinned.

Latest published version: immutable, used only when explicitly selected.

Existing Agent pin: stable and used by the Runtime; “latest” is never implicit resolution.

An Agent Override source update selects a complete newer snapshot from its direct Platform or Organization source. It changes the Agent’s shared source pin and does not mutate, merge, discard, or publish an existing private Override Draft.

A Skill fork is an independent lineage that records its exact direct source Skill and source version. Organizations can fork visible Platform Skills; Agents can fork visible Platform or Organization Skills into private Agent lineages. Update availability is calculated against the direct source lineage. If no draft exists, Apply Update copies the newest direct source and publishes the next fork version immediately. If a draft exists, it replaces draft files and staged metadata for review without publishing. Source updates are replacement-based, never merges; they do not move existing Agent or Template pins or affect sibling forks.

A Template or Agent Override requirement identifies both the required Skill lineage and its exact immutable Skill Version. An Agent assignment also pins an exact Skill Version. Applying another Template Version revalidates requirements from that exact snapshot, while Agent creation, configuration, and repinning validate provider requirements against the resulting Agent Secrets.

A Skill declares required providers but grants no credentials, permissions, or tools. Eligible bundled provider Skills may mount automatically when their supported provider credential is configured, but automatic availability never replaces explicit assignment when a Template requires the Skill.

Bundled Skills live in isolated aai-<integration>/ directories. Each bundle contains exactly one root SKILL.md and optional relative reference files. Bootstrap publishes only missing Platform Skill lineages; the database remains canonical afterward. Platform, Organization, and Agent authors use the same draft-first model: new content is unavailable until published and explicitly pinned.

Published history can be removed only when no remaining resource depends on it. Version deletion checks direct Agent pins, Template and Override requirements, drafts, and fork-source provenance; lineage deletion additionally requires the caller to manage its owning scope. Built-in bundled aai_cli Platform Skill lineages cannot be deleted, and soft-deleted Agent references still protect pinned versions. Removing an unused historical version does not change Runtime behavior because consumers use exact pins.

A Skill Version cannot be deleted if it is the lineage’s last published version, an Agent pins it, a Template or Agent Override requires it, a draft references it, or a fork records it as source. A custom Skill lineage can be deleted only when no Agent pins any version, no Template or Override requires one, and no draft or fork-source reference depends on it. Lineage deletion removes its draft, versions, and files; deleting a visible latest version is not safe merely because no running Agent uses it.

Across scopes, each Platform Template, Organization Template, Agent Template Override, Platform Skill, Organization Skill, and Agent-private Skill has one scope-owned mutable draft and immutable published consumer versions. Exact management controls vary by scope; published-version immutability does not. Continue with /guides/templates-and-skills/templates, /guides/templates-and-skills/template-versions, /guides/templates-and-skills/agent-overrides, /guides/templates-and-skills/skills, /guides/templates-and-skills/skill-scopes, /guides/templates-and-skills/skill-versions, and /guides/templates-and-skills/forks-and-updates for focused workflows.