# 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](https://docs.mindset.ai/docs/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:

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 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:

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

```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

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

```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:

| 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

```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

| 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](https://docs.mindset.ai/openapi/customer-v1.json).
