Skills

A skill packages a SKILL.md and optional supporting files. Upload it once, attach it to agents or to a single session, 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. A revision’s version id is skr_….
Frozen per session: a session fixes every skill at a concrete skr_… version when it is created and keeps it for its whole life.
Shared: a skill is owned by an org, project or user and granted to projects.

Create and manage skills with the BMA extension /v1/skills (POST /v1/skills is a multipart upload of a folder with a SKILL.md; uploading a name that exists is its next revision, and latest_version_id is the new skr_…); see the API reference.

Attach to an agent

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

version may be omitted or "latest", which means the newest revision at the moment a session is created, or a skr_… version, which pins that revision for every session of the agent. type: "anthropic" (Anthropic’s prebuilt skills) is rejected. The agent resource keeps showing what you wrote ("latest" stays "latest"); the resolved version is on the session.

Change skills for one session

Pass agent_with_overrides when you create a session. skills replaces the agent’s list for this session only; the agent and its version are not touched, so other sessions of the same agent are unaffected.

session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        "skills": [{"type": "custom", "skill_id": "skl_..."}],
    },
    environment_id=environment.id,
)

curl https://api.staging.bma.beeos.ai/v1/sessions \
  -H "x-api-key: $BMA_API_KEY" -H "content-type: application/json" \
  -d '{
    "agent": {
      "type": "agent_with_overrides",
      "id": "'"$AGENT_ID"'",
      "skills": [{"type": "custom", "skill_id": "skl_..."}]
    },
    "environment_id": "'"$ENV_ID"'"
  }'

`skills` in the override	The session gets
omitted	the agent’s skills
`[]` or `null`	no skills
a list	exactly that list (never merged with the agent’s)

Whole-list replacement. To add one skill to what the agent has, read the agent, append, and send the full list.
Creation only. POST /v1/sessions/{id} with agent.skills is 400 unsupported; to use other skills, start a new session.
Limits. At most 500 skills per session. A skill_id must be owned by the session’s project or granted to it; a skill that does not exist and one you cannot see are both 404.

Versions are frozen at creation

When a session is created, each skill in its effective list is resolved once:

You wrote	The session records
no `version` or `"latest"`	the newest revision at that moment
`skr_…`	that revision (must exist)

Read it back from session.agent.skills[].version on create, retrieve and list: it is the resolved skr_…, never "latest".

for skill in session.agent.skills:
    print(skill.skill_id, skill.version)  # skl_...  skr_...

Running sessions do not upgrade. A skill revision uploaded after the session was created is not seen by that session (instructions, supporting files and /mnt/skills all stay on the frozen revision). New sessions get the new revision. To move to it, start a new session.
Same for every new session, with or without an override.
Deleted revisions. If the frozen revision is deleted while the session is alive, the skill disappears from that session’s skill tool and /mnt/skills; the session record is not rewritten.

Errors

Errors use the standard envelope. The reason is in error.bma_error_code; error.code carries the same value during the migration.

Situation	HTTP	`error.type`	`bma_error_code`
`skill_id` does not exist or is not visible to the project	404	`not_found_error`	`skill_not_found`
`version` does not exist or was deleted	404	`not_found_error`	`skill_version_not_found`
More than 500 skills	400	`invalid_request_error`	`too_many_skills`
`type: "anthropic"`	400	`invalid_request_error`	`unsupported`
Missing or unknown `type`	400	`invalid_request_error`	—
`agent.skills` on `POST /v1/sessions/{id}`	400	`invalid_request_error`	`unsupported`

Creating or updating an agent that names a skill you cannot use gets the same 404 skill_not_found.

What happens at run time

When the model calls skill, BMA returns the instructions of the session’s frozen revision and installs the supporting files on the session’s computer (API resource: machine). Because skill installs files, it counts as a machine tool: the session’s computer is created if it does not exist yet. The instructions are still returned when installation fails. See Machines & pools.

Get started

Concepts

Executor & brains

Attach to an agent

Change skills for one session

Versions are frozen at creation

Errors

What happens at run time

​Attach to an agent

​Change skills for one session

​Versions are frozen at creation

​Errors

​What happens at run time

Attach to an agent

Change skills for one session

Versions are frozen at creation

Errors

What happens at run time