--- title: Skill scopes canonical: "https://agentbarn.dev/guides/templates-and-skills/skill-scopes" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-13T13:41:42.000Z" author: Agent Barn description: "Choose the right Agent Barn Skill scope, understand Platform, Organization, and Agent-private visibility, and manage exact version pins and forks safely." tags: [Templates and Skills, Concept, "Skill authors, Agent operators, Organization administrators, Agent editors, and Platform Administrators", Skill scopes, Platform Skill, Organization Skill, Agent-private Skill, Skill ownership, Skill visibility, skill.manage, Agent Access, Skill fork, Skill assignment] categories: [Guides, Templates and Skills] --- - Templates and Skills - 10–12 minutes Skill scope determines ownership, visibility, management authority, available UI and API routes, valid fork directions, and which Agents and Templates may reference a Skill. **Scope does not change lifecycle** Every scope uses the same lifecycle: `Lineage → Draft → Immutable Published Versions`. Agents and Templates always pin exact published Skill Versions. ## Choose the ownership scope | Scope | Owner | Visibility | Typical use | | --- | --- | --- | --- | | Platform | Agent Barn platform | Available across Organizations | Bundled integrations and globally curated capabilities | | Organization | One Organization | That Organization and its Agents | Shared company workflows and policies | | Agent | One Agent within an Organization | Only the owning Agent | Private role-specific or customer-specific instructions | Conceptually, a Platform Skill has no Organization or Agent owner; an Organization Skill has an Organization owner and no Agent owner; an Agent Skill has both Organization and Agent owners. Scope is fixed by creation context; it is not changed later with an update field. ## Use additive Agent visibility ``` Skills visible to an Agent ├── Platform Skills ├── Skills owned by the Agent’s Organization └── Skills privately owned by that Agent ``` | Skill owner | Same Organization user | Owning Agent | Different Agent in same Organization | Different Organization | | --- | --- | --- | --- | --- | | Platform | Visible | Visible | Visible | Visible | | Organization | Visible | Visible | Visible | Not visible | | Agent-private | Only through access to the Agent | Visible | Not visible | Not visible | An Agent cannot see another Organization’s Skills, another Agent’s private Skills, or inaccessible draft-only content. Platform visibility means available subject to normal authentication and resource permissions; it does not make Platform definitions customer-editable. ## Manage Platform Skills globally Platform Skills are global resources: bundled `aai-cli` Skills and custom Platform Skills created by Platform Administrators. Use them for consistently available capabilities across customer Organizations. ``` aai-/ ├── SKILL.md └── optional supporting files ``` - Platform Administrators manage definitions; Organizations and Agents see them as shared, read-only resources. - An Organization or Agent may fork an eligible visible Platform Skill into an owned scope, but cannot edit it in place. - Built-in `aai_cli` lineages are protected from whole-lineage deletion, and published versions remain immutable. - Publishing a Platform Skill Version never repins existing consumers. ## Share Organization Skills deliberately Organization Skills are appropriate for company procedures, internal tools, terminology, and standard support or incident workflows reused by multiple Agents. They are visible only to their Organization and its Agents. - `skill.read` reads shared Skills; `skill.manage` creates, renames, drafts, publishes, forks, applies source updates, and deletes eligible versions or unused lineages. - The fixed Organization Member role may read and use shared Skills but cannot mutate definitions; Organization Owner and Admin roles receive management authority. - A Platform fork becomes an Organization-owned lineage with its own draft and version history. - Publishing never repins Agents or Templates automatically. ## Keep Agent-private Skills isolated Agent-private Skills are for one Agent’s role-specific instructions, experiments, customer procedures, or private variations of shared content. They retain the Agent’s Organization for tenant isolation but are not shared Organization definitions. - Reads require access to the owning Agent; mutation requires `agent.update`. - Agent-scoped routes provide the complete lifecycle. Organization routes and direct URLs must enforce the same Agent Access boundary and cannot reveal a sibling Agent’s private Skill. - An Agent can fork a visible Platform or Organization Skill into an independently versioned private lineage. - Private custom-lineage deletion still requires the lineage to be unused and unreferenced. ## Match authority to the owning scope | Action | Platform Skill | Organization Skill | Agent-private Skill | | --- | --- | --- | --- | | View | Platform-authorized surface; visible downstream | skill.read | agent.read | | Create | Platform Administrator | skill.manage | agent.update | | Edit draft | Platform Administrator | skill.manage | agent.update | | Publish | Platform Administrator | skill.manage | agent.update | | Delete eligible version | Platform Administrator | skill.manage | agent.update | | Delete eligible lineage | Platform Administrator; custom only | skill.manage; custom only | agent.update; custom only | | Fork into this scope | Not applicable | skill.manage | agent.update | **Shared-definition and Agent authority are separate** `skill.manage` controls shared Organization definitions; `agent.update` controls one Agent’s configuration, assignments, and private Skills. A user may assign an already visible published shared Skill to an Agent they can configure without being allowed to edit that shared definition. Internal Agent workflows do not grant `skill.manage`. Scope management never bypasses tenant isolation, exact-version reference protection, last-version or built-in-lineage protection, Agent Access, or fork-source protection. ## Follow supported fork directions | Source scope | Platform destination | Organization destination | Agent destination | | --- | --- | --- | --- | | Platform | Not applicable | Allowed | Allowed | | Organization | Not allowed | Not applicable | Allowed | | Agent | Not allowed | Not allowed | Not applicable | Platform is the root scope. Organization forks originate only from Platform Skills; Agent-private forks originate from Platform or Organization Skills. Private content cannot be promoted by changing its owner, and one Agent cannot fork another Agent’s private Skill because it is not visible. A fork records its exact direct source Skill ID and version. ## Keep scope and source distinct Scope says who owns a Skill. Source says how the current draft or published version originated. “Built-in,” “Platform,” “Organization,” “custom,” and “fork” are not interchangeable terms. ``` Platform custom Skill Scope: Platform Source type: Custom Bundled aai-github Skill Scope: Platform Source type: aai_cli Organization fork of Platform Skill v3 Scope: Organization Direct source: Platform Skill v3 Agent-private fork of Organization Skill v2 Scope: Agent Direct source: Organization Skill v2 ``` ## Assign and require Skills within visibility boundaries ``` Platform + Organization + owning Agent-private skill_id + pinned_version ``` A selected version must exist in a visible lineage. Scope does not make an Agent follow latest; drafts cannot be assigned; publishing never moves an assignment. Required providers are validated against the Agent’s configured tool Integration Secrets. Skills do not grant permissions, credentials, tools, or Communication Connections. Templates require exact published Skill Versions. Platform Templates use Platform Skills; Organization Templates use visible Platform and Organization Skills; Agent Template Overrides operate inside their owning Agent’s visibility boundary. A shared Template cannot use another Organization’s or another Agent’s private Skill, and publishing newer Skill content never rewrites an existing Template Version. ## Use scope-specific UI and API routes ### Platform Skills ``` /dashboard/platform/skills /dashboard/platform/skills/new /dashboard/platform/skills/{skill_id} ``` ### Organization Skills ``` /dashboard/{org_id}/settings?tab=skills /dashboard/{org_id}/settings/skills/new /dashboard/{org_id}/settings/skills/{skill_id} ``` ### Agent-private Skills ``` /dashboard/{org_id}/agents/{agent_id}/configuration?section=skills /dashboard/{org_id}/agents/{agent_id}/skills/new /dashboard/{org_id}/agents/{agent_id}/skills/{skill_id} ``` Mixed lists should show scope badges. Management controls appear only when the caller can mutate the selected Skill in its owning scope. ``` Platform /api/v1/platform/skills Organization /api/v1/organizations/{organization_id}/skills Agent-private /api/v1/organizations/{organization_id}/agents/{agent_id}/skills ``` Each prefix provides its applicable list, detail, draft, publish, history, and deletion operations. Organization and Agent prefixes also provide supported `POST /{skill_id}/fork` and `POST /{skill_id}/source-update` actions. Ownership comes from the route and creation context, not an update-body scope or owner field. ## Select the narrowest useful scope ``` Should every Organization be able to use this Skill? ├── Yes → Platform Skill └── No └── Should multiple Agents in one Organization share it? ├── Yes → Organization Skill └── No → Agent-private Skill ``` - Use Organization scope for shared internal standards and Agent scope for isolated experimentation. - Use a fork when customization should retain source provenance. - Do not put customer-specific content in a Platform Skill. - Do not duplicate an Organization Skill privately unless the Agent needs an independent version lifecycle. ### `aai-github` A bundled Platform Skill available across Organizations; Organizations can use or fork it for local guidance. ### Company incident response An Organization Skill shared by support, engineering, and operations Agents. ### Enterprise customer escalation rules An Agent-private Skill owned by one account-management Agent and hidden from sibling Agents. ## Preserve isolation and safety - Scope checks happen at every user-facing service boundary, not as a client-only filter. - Agent-private routes remain subordinate to Agent Access; unavailable private lineages must not leak metadata. - An Organization identifier cannot make another Organization’s Skill visible. - Skill files do not contain or return Agent Secrets automatically, and provider requirements are metadata rather than authorization grants. - Published versions and fork-source references protect consumers from dangling references. ## Next steps - [Work with Skills](/guides/templates-and-skills/skills) and [Manage Skill Versions](/guides/templates-and-skills/skill-versions) - [Manage Forks and Updates](/guides/templates-and-skills/forks-and-updates) - [Work with Templates](/guides/templates-and-skills/templates) and [Use Agent Overrides](/guides/templates-and-skills/agent-overrides) - [Configure an Agent](/guides/agents/configuration) and [Roles, Permissions, and Agent Access](/guides/observe-and-govern/roles-and-permissions) - [Explore integrations](/guides/integrations) and [manage credentials](/guides/integrations/credentials)