ReferenceAPISkills API

Updated 11 Nov 2026View as Markdown

Skills API

The server-to-server routes that keep an environment's Skills in step with the ones your system holds: endpoints, request and response fields, activating a version, enabling and disabling a Skill, listing, deleting, limits, errors and what version 1 promises.

Your system lists an environment's Skills, pushes the ones it keeps, chooses which version is active and whether each Skill is enabled, reads them back and deletes the ones it no longer has, with an org API key. No person and no AI model takes part. A Skill is used only while it is enabled and a version of it is active. It reaches an agent once it is attached to that agent and a person activates the agent version the attach saves; this API doesn't attach. A single embedded session can also be given a Skill with no attach: see additionalResources.skills in the Session API.

Before you start#

KeyCreated in Settings → API keys, in the same environment as envSlug. Choose Skills only under Access: that key lists, reads, pushes, activates, enables, disables and deletes Skills and reaches nothing else. A Full access key works too
HeaderThe key in x-api-key
CallersServers only. Keep the key out of a browser
Base pathhttps://YOUR-MINDSET-HOST/api/v1/orgs/{orgSlug}/envs/{envSlug}

Endpoints#

Method and pathWhat it doesScope
GET /skillsEvery Skill in the environment, in byte order of the handle, a page at a timeskills:read
PUT /skills/{handle}Makes the Skill at this handle equal the body, then applies activateskills:write
DELETE /skills/{handle}Deletes the Skill, with every versionskills:write
GET /skills/{handle}The Skill and its newest version, in fullskills:read
GET /skills/{handle}/versionsIts versions, newest first, a page at a timeskills:read
GET /skills/{handle}/versions/{version}One version, in fullskills:read
POST /skills/{handle}/versions/{version}/activateMakes that version the Skill's active versionskills:write
POST /skills/{handle}/enableEnables the Skill, so the agents that hold it load its active versionskills:write
POST /skills/{handle}/disableDisables the Skill, so no agent loads itskills:write

A handle is 1 to 64 lowercase letters, digits and hyphens, with no hyphen at either end and no two in a row: invoice-exceptions. Every route names the Skill by its handle.

Keep an environment in step#

A system that holds the Skills an environment should have makes four kinds of call:

  1. GET /skills, following nextCursor to the last page, for the handles the environment has now and whether each is enabled.
  2. PUT /skills/{handle} for each Skill the system holds, with activate as it should be. A Skill that hasn't changed answers unchanged and adds nothing, so pushing every one on every run is safe.
  3. POST /skills/{handle}/enable for each Skill that should be in use and isn't enabled, since a new Skill starts disabled, and POST /skills/{handle}/disable for one the system keeps but shouldn't be used.
  4. DELETE /skills/{handle} for each handle the environment has that the system doesn't.

From a SKILL.md folder#

A Skill in the Agent Skills format is a folder: a SKILL.md that opens with frontmatter between two --- lines, and other files beside it.

In the folderIn the push
The frontmatter's nameThe handle, in the path
The frontmatter's description, license, compatibility, metadata and allowed-toolsdescription, license, compatibility, metadata and allowedTools
Everything after the line that closes the frontmatter, the blank line that usually follows it includedinstructions, exactly as it is
Every other file, by its path from the folderfiles, each path to its text
Nothingname, a display name you choose, such as the first heading. Agents see it beside the description

For example, this folder:

text
invoice-exceptions/
  SKILL.md
  references/tolerances.md
  scripts/check_totals.py

with this SKILL.md:

markdown
---
name: invoice-exceptions
description: Use when an invoice does not match its purchase order.
license: Proprietary
metadata:
  owner: finance-ops
---

# Invoice exceptions

Flag any line over 5% of the agreed price.

is this push, to PUT /skills/invoice-exceptions. The instructions start with the blank line that follows the frontmatter, and the script is left out:

json
{
  "name": "Invoice exceptions",
  "description": "Use when an invoice does not match its purchase order.",
  "license": "Proprietary",
  "metadata": { "owner": "finance-ops" },
  "instructions": "\n# Invoice exceptions\n\nFlag any line over 5% of the agreed price.\n",
  "files": { "references/tolerances.md": "| Category | Tolerance |\n|---|---|\n| Goods | 2% |\n" },
  "activate": true
}

Leave out files that are programs: anything under scripts/, and any file ending .py, .sh, .bash, .zsh, .js, .mjs, .cjs, .ts, .rb, .pl, .php, .ps1, .bat, .cmd or .exe. Mindset doesn't run them, and refuses a push that holds one with reason scripts_not_supported.

Push a Skill#

bash
curl -X PUT "https://YOUR-MINDSET-HOST/api/v1/orgs/acme/envs/production/skills/invoice-exceptions" \
  -H "x-api-key: $SKILLS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Invoice exceptions",
    "description": "Use when an invoice does not match its purchase order.",
    "instructions": "# Invoice exceptions\n\nCompare the invoice lines with the purchase order. Flag any line over 5% of the agreed price.",
    "files": { "references/tolerances.md": "| Category | Tolerance |\n|---|---|\n| Freight | 10% |\n" },
    "activate": true
  }'

The call is declarative: send the whole Skill as it should be.

Before the callWhat happensStatusoutcome
No Skill at the handleThe Skill is created at version 1201created
A Skill whose newest version differsOne version is added200updated
A Skill whose newest version is this documentNothing is added200unchanged

So a retried call never creates a second Skill or a second version. A different name is a change like any other: it adds a version carrying the new name, and agents see the new name once that version is active.

Request body

FieldTypeRequiredNotes
namestringyesThe display name, 1 to 255 characters. Every agent the Skill is attached to sees the active version's name beside the description, and the Studio shows it
descriptionstringyesWhen the Skill applies, up to 1,024 characters. An agent reads it to decide whether to load the Skill
instructionsstringyesThe body of the Skill's SKILL.md
filesobjectnoOther text files, by path relative to the Skill's root: { "references/tolerances.md": "…" }. No scripts, no binary files, no SKILL.md
licensestringnoUp to 500 characters
compatibilitystringnoUp to 500 characters
metadataobjectnoUp to 50 entries, each key up to 64 characters and each value up to 500
allowedToolsstringnoKept as written. It has no effect in Mindset
activatebooleanyestrue makes this version the Skill's active version. false stores it and leaves the active version as it was. It never enables or disables the Skill

The body is strict: a field not in this table is refused, and the refusal names it. Instructions and files are stored byte for byte as sent, line endings and trailing spaces included.

Activating a version

activate is required on every push. With true, the pushed version becomes the Skill's active version in the same step, and the version that was active stops being active. A Skill never has more than one active version, even when two pushes arrive at the same moment. With false, the version is stored and nothing agents load changes: the active version stays active, and a Skill with none stays unused. Push the same document again with true when it should become active.

activate never enables or disables the Skill. A new Skill starts disabled, whatever activate says, and agents use it only once it is enabled (see "Enable and disable a Skill" below). On a Skill that is already enabled, activate: true puts the pushed version in front of every agent that holds the Skill, from its next turn.

Activating is refused with 400 validation_error and reason live_skill_cap when the Skill is enabled with no version active and an agent it is attached to already holds 50 Skills in use, since this would make one more. An org admin attaches Skills to agents through the mindset-admin MCP server; this API doesn't.

Activate another version

POST /skills/{handle}/versions/{version}/activate makes the version you name the Skill's active version: a version never active before, an earlier one, or the active one, which changes nothing. While the Skill is enabled, agents load it from their next turn. Nothing is copied and no version is added, so this is how to bring back an earlier version. It never enables the Skill. It is refused with 400 validation_error when the version isn't a whole number from 1, or, with reason live_skill_cap, when the Skill is enabled with no version active and an agent it is attached to would hold more than 50 Skills in use.

It answers with the Skill itself as the whole body, the same shape as a push's skill. A call that changes something is recorded in the org's audit trail, naming the key; activating the version already active records nothing.

bash
curl -X POST "https://YOUR-MINDSET-HOST/api/v1/orgs/acme/envs/production/skills/invoice-exceptions/versions/2/activate" \
  -H "x-api-key: $SKILLS_API_KEY"

Conditions

HeaderEffect
If-None-Match: *Create only. A 412 if a Skill already holds the handle
If-Match: "3"Store the push, or make the delete, only while version 3 is still the newest. A 412 if it has moved

GET /skills/{handle} and every push return the newest version as the ETag, ready for If-Match; a read of one version does not. Writes to one Skill are taken one at a time, from this API and the mindset-admin MCP server alike.

Response

FieldWhat it is
outcomecreated, updated or unchanged
skillThe Skill: id, handle, name, activeVersion (the active version, or null), enabled (whether the Skill is enabled), createdBy, createdAt, updatedAt
versionThe version the pushed document is
activeWhether that version is the Skill's active version after the call. Agents load it only while the Skill is also enabled, which a push never changes
warningsAdvice the content earned, such as instructions longer than the Agent Skills specification recommends. The push still succeeded

Enable and disable a Skill#

A Skill is used only while it is enabled and a version of it is active. A new Skill starts disabled.

POST /skills/{handle}/enable enables it: from the next turn, every agent that holds it is told of it and loads its active version. It is refused with 400 validation_error when no version is active (reason no_active_version: activate one first), or when an agent that holds it would then have more than 50 Skills in use (reason live_skill_cap).

POST /skills/{handle}/disable disables it: from the next turn no agent is told of it or loads it, though agents keep holding it, and no embedded session can add it. Its active version stays active, so enabling it again uses the same version, and every version is kept.

Both answer with the Skill itself as the whole body, the same shape as a push's skill. A change is recorded in the org's audit trail, naming the key. A Skill already in the state asked for answers the same, and nothing is recorded.

To act only on the state your system last read, send shownEnabled with that state: { "shownEnabled": false } before enabling a Skill you read as disabled. When the Skill is no longer in that state, nothing changes and the answer is 409 enabled_state_changed, with the state now in context.enabled. With no body, the call acts whatever the state is.

bash
curl -X POST "https://YOUR-MINDSET-HOST/api/v1/orgs/acme/envs/production/skills/invoice-exceptions/enable" \
  -H "x-api-key: $SKILLS_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "shownEnabled": false }'

Read a Skill#

GET /skills/{handle} and GET /skills/{handle}/versions/{version} return:

FieldWhat it is
skillThe Skill, as in a push's response
versionThe version's record: id, version, name (the name this version carries), description, author and authorLabel (who wrote it), activatedBy, activatedByLabel and activatedAt (who first activated it, and when), isActive, totalBytes, createdAt, and parentVersionId (the version this one was built on)
documentEverything the version holds, in the shape a push takes, its name included

Read document, change it, and push it back with activate to make a change.

GET /skills/{handle}/versions returns versions, newest first, and nextCursor. Pass ?limit= for the page size (50 unless you ask, at most 200) and ?cursor= with the last page's nextCursor for the versions before it. nextCursor is null on the last page. When the limit you sent was over 200, the page holds 200 and the answer carries limitClamped, saying so.

List Skills#

GET /skills returns skills, in byte order of the handle (- before digits, digits before letters), and nextCursor. Each entry is the Skill, as in a push's response, with newestVersion: the newest version's number, active or not. Pass ?limit= for the page size (50 unless you ask, at most 200; a larger number reads 200 and the answer's limitClamped says so) and ?cursor= with the last page's nextCursor for the Skills after it. nextCursor is null on the last page. A cursor is opaque: pass it back as you got it.

A Skill created or deleted while you page moves no other Skill between pages. A deleted Skill isn't listed, and neither is another environment's.

Delete a Skill#

bash
curl -X DELETE "https://YOUR-MINDSET-HOST/api/v1/orgs/acme/envs/production/skills/invoice-exceptions" \
  -H "x-api-key: $SKILLS_API_KEY"

A 200 returns deleted: true and skill, the Skill as it was. It is gone with every version: agents stop loading it, and it is no longer read or listed. Its handle is free, so a later push to it creates a new Skill at version 1. A delete is recorded in the org's audit trail, naming the key, and isn't undone through this API.

When agents' active versions hold the Skill, the first delete removes nothing. It answers 409 has_dependents, with the agents in context.dependents and a context.fingerprint for that list. Show the list to whoever decides, and to delete anyway, repeat the call with ?confirmDependents= and the fingerprint. If the agents holding it have changed since, the answer is 409 dependents_changed with the current list and a new fingerprint. A Skill no agent holds is deleted on the first call.

With If-Match: "3", the Skill is deleted only while version 3 is still its newest; if a newer version has been pushed since you read it, the answer is 412 precondition_failed and nothing is deleted.

A delete where there is no Skill, a retried delete that already succeeded among them, answers 404.

Limits#

WhatLimit
One version, instructions and files together, as stored4 MiB (4,194,304 bytes)
The request body16 MiB (16,777,216 bytes), so a Skill at its limit fits once escaped as JSON
Files in one version10,000
A file's path512 characters

A Skill over a limit is refused naming the limit and its size. Nothing is stored.

Errors#

Every error body is JSON with a code, a message, and often a context. An invalid Skill is refused once, with every problem in context.problems, each with its field and reason (up to 20, and context.problemsTotal when there are more).

What happenedStatuscode
A body that isn't JSON, misses a field, carries one this API doesn't define, or breaks a rule, including text that can't be stored as sent (a NUL character, or half of an emoji); or a limit, cursor or confirmDependents that isn't valid, or a query parameter the route doesn't define (named in the message)400validation_error
A handle that isn't a valid handle400invalid_handle
No key in x-api-key401unauthorized
A key that is unknown, revoked or expired401invalid_api_key
A platform key sent instead of an org API key403credential_kind_not_accepted
A suspended org403org_suspended
No such Skill or version404not_found
A request the key may not make: it lacks the scope (a push, activate, enable, disable or delete with a key that can only read Skills), or the org or environment in the path isn't its own404not_found
Enabling a Skill with no active version400validation_error, reason no_active_version
Activating or enabling would give an agent more than 50 Skills in use400validation_error, reason live_skill_cap
Another change to the same Skill, made at the same moment, got there first. Read it again and retry409version_conflict
An enable or disable whose shownEnabled isn't the Skill's state now409enabled_state_changed
A delete of a Skill agents hold, without confirmDependents409has_dependents
A delete whose confirmDependents no longer matches the agents holding the Skill409dependents_changed
An If-None-Match or If-Match condition that didn't hold412precondition_failed
An If-Match that names no version, an If-None-Match other than * on a push, or If-None-Match on a delete400validation_error
A body over 16 MiB413payload_too_large
A limit that keeps the Mindset instance serving everyone was reached. Nothing was stored: wait the seconds in Retry-After, then send it again429rate_limited

The 404s for a wrong org, environment or key look the same on purpose, so nobody holding a key can learn which orgs or environments exist.

What version 1 promises#

Within /api/v1, changes only add: new routes, new optional request fields, new response fields and new error codes. Ignore response fields you don't know, and treat an unknown code by its status. Nothing here is removed, renamed or narrowed within v1. A change that would break a caller ships as /api/v2 beside /api/v1, which keeps answering through a declared deprecation window and says so in Deprecation and Sunset headers.

Every change (a push that adds a version, an activation that moves which version is active, an enable or a disable, a delete) is recorded in the org's audit trail, naming the key; a call that changes nothing records nothing. Every call is counted against the key that made it.

The OpenAPI 3.1 document for these routes, generated from the code that serves them, is customer-v1.json.