ReferenceAPISkills API
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#
| Key | Created 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 |
| Header | The key in x-api-key |
| Callers | Servers only. Keep the key out of a browser |
| Base path | https://YOUR-MINDSET-HOST/api/v1/orgs/{orgSlug}/envs/{envSlug} |
Endpoints#
| Method and path | What it does | Scope |
|---|---|---|
GET /skills | Every Skill in the environment, in byte order of the handle, a page at a time | skills:read |
PUT /skills/{handle} | Makes the Skill at this handle equal the body, then applies activate | skills:write |
DELETE /skills/{handle} | Deletes the Skill, with every version | skills:write |
GET /skills/{handle} | The Skill and its newest version, in full | skills:read |
GET /skills/{handle}/versions | Its versions, newest first, a page at a time | skills:read |
GET /skills/{handle}/versions/{version} | One version, in full | skills:read |
POST /skills/{handle}/versions/{version}/activate | Makes that version the Skill's active version | skills:write |
POST /skills/{handle}/enable | Enables the Skill, so the agents that hold it load its active version | skills:write |
POST /skills/{handle}/disable | Disables the Skill, so no agent loads it | skills: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:
GET /skills, followingnextCursorto the last page, for the handles the environment has now and whether each isenabled.PUT /skills/{handle}for each Skill the system holds, withactivateas it should be. A Skill that hasn't changed answersunchangedand adds nothing, so pushing every one on every run is safe.POST /skills/{handle}/enablefor each Skill that should be in use and isn't enabled, since a new Skill starts disabled, andPOST /skills/{handle}/disablefor one the system keeps but shouldn't be used.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 folder | In the push |
|---|---|
The frontmatter's name | The handle, in the path |
The frontmatter's description, license, compatibility, metadata and allowed-tools | description, license, compatibility, metadata and allowedTools |
| Everything after the line that closes the frontmatter, the blank line that usually follows it included | instructions, exactly as it is |
| Every other file, by its path from the folder | files, each path to its text |
| Nothing | name, a display name you choose, such as the first heading. Agents see it beside the description |
For example, this folder:
invoice-exceptions/
SKILL.md
references/tolerances.md
scripts/check_totals.pywith this SKILL.md:
---
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:
{
"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#
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 call | What happens | Status | outcome |
|---|---|---|---|
| No Skill at the handle | The Skill is created at version 1 | 201 | created |
| A Skill whose newest version differs | One version is added | 200 | updated |
| A Skill whose newest version is this document | Nothing is added | 200 | unchanged |
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
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | The 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 |
description | string | yes | When the Skill applies, up to 1,024 characters. An agent reads it to decide whether to load the Skill |
instructions | string | yes | The body of the Skill's SKILL.md |
files | object | no | Other text files, by path relative to the Skill's root: { "references/tolerances.md": "…" }. No scripts, no binary files, no SKILL.md |
license | string | no | Up to 500 characters |
compatibility | string | no | Up to 500 characters |
metadata | object | no | Up to 50 entries, each key up to 64 characters and each value up to 500 |
allowedTools | string | no | Kept as written. It has no effect in Mindset |
activate | boolean | yes | true 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.
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
| Header | Effect |
|---|---|
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
| Field | What it is |
|---|---|
outcome | created, updated or unchanged |
skill | The Skill: id, handle, name, activeVersion (the active version, or null), enabled (whether the Skill is enabled), createdBy, createdAt, updatedAt |
version | The version the pushed document is |
active | Whether 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 |
warnings | Advice 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.
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:
| Field | What it is |
|---|---|
skill | The Skill, as in a push's response |
version | The 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) |
document | Everything 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#
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#
| What | Limit |
|---|---|
| One version, instructions and files together, as stored | 4 MiB (4,194,304 bytes) |
| The request body | 16 MiB (16,777,216 bytes), so a Skill at its limit fits once escaped as JSON |
| Files in one version | 10,000 |
| A file's path | 512 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 happened | Status | code |
|---|---|---|
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) | 400 | validation_error |
| A handle that isn't a valid handle | 400 | invalid_handle |
No key in x-api-key | 401 | unauthorized |
| A key that is unknown, revoked or expired | 401 | invalid_api_key |
| A platform key sent instead of an org API key | 403 | credential_kind_not_accepted |
| A suspended org | 403 | org_suspended |
| No such Skill or version | 404 | not_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 own | 404 | not_found |
| Enabling a Skill with no active version | 400 | validation_error, reason no_active_version |
| Activating or enabling would give an agent more than 50 Skills in use | 400 | validation_error, reason live_skill_cap |
| Another change to the same Skill, made at the same moment, got there first. Read it again and retry | 409 | version_conflict |
An enable or disable whose shownEnabled isn't the Skill's state now | 409 | enabled_state_changed |
A delete of a Skill agents hold, without confirmDependents | 409 | has_dependents |
A delete whose confirmDependents no longer matches the agents holding the Skill | 409 | dependents_changed |
An If-None-Match or If-Match condition that didn't hold | 412 | precondition_failed |
An If-Match that names no version, an If-None-Match other than * on a push, or If-None-Match on a delete | 400 | validation_error |
| A body over 16 MiB | 413 | payload_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 again | 429 | rate_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.