Skills API

Before you start#

Endpoints#

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 three kinds of call:

1. GET /skills, following nextCursor to the last page, for the handles the environment has now.
2. PUT /skills/{handle} for each Skill the system holds, with live 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. 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.

For example, this folder:

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

with 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" },
  "live": 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" },
    "live": true
  }'

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

So a retried call never creates a second Skill or a second version. A different name renames the Skill and adds no version.

Request body

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.

Going live

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

Going live is refused when an agent the Skill is attached to already holds 50 published Skills, since this would make one more. An org admin attaches Skills to agents through the mindset-admin MCP server; this API doesn't.

Conditions

Every read of a Skill and every push returns the newest version as the ETag, ready for If-Match. Writes to one Skill are taken one at a time, from this API and the mindset-admin MCP server alike.

Response

Read a Skill#

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

Read document, change it, and push it back with live 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.

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, live 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 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#

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

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 push and every delete is recorded in the org's audit trail, naming the key, and 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.