Skill scopes

Choose the ownership scope

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

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-<integration>/
├── 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

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

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

/dashboard/platform/skills
/dashboard/platform/skills/new
/dashboard/platform/skills/{skill_id}

/dashboard/{org_id}/settings?tab=skills
/dashboard/{org_id}/settings/skills/new
/dashboard/{org_id}/settings/skills/{skill_id}

/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.

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 and Manage Skill Versions
• Manage Forks and Updates
• Work with Templates and Use Agent Overrides
• Configure an Agent and Roles, Permissions, and Agent Access
• Explore integrations and manage credentials