Skills - BMA Developer Docs

A skill packages a SKILL.md and optional supporting files. Upload it once, attach it to agents, and the model loads it with the built-in skill tool when it decides it needs it.

Lazy: only the skill’s name and description are in the model’s context until it is loaded.
Versioned: uploading the same skill again creates a new revision under the same skl_… id. Agents always run the latest revision.
Shared: a skill is owned by an org, project or user and granted to projects.

Attach

Managed Agents API (/v1)
Native API

{
  "skills": [{"type": "custom", "skill_id": "skl_...", "version": "latest"}]
}

version may be omitted or "latest". Pinned versions and type: "anthropic" (Anthropic’s prebuilt skills) are rejected. Skills cannot be replaced per session.

skills:
  - skl_...

Upload with POST /orgs/{org}/skills (a folder archive or a single SKILL.md), grant it to projects, then reference the id. Config creation checks that the project can use it.

What happens at run time

When the model calls skill, BMA returns the instructions and installs the supporting files on the session’s machine. Because skill installs files, it counts as a machine tool: the session’s machine is created if it does not exist yet. The instructions are still returned when installation fails.