# Skills

> Save a job once as a skill, including a standard SKILL.md, then call it by its model name.

A skill is the job your agent does, written as a short Markdown procedure with numbered steps. Save it once and every run of that job can name it. A standard `SKILL.md`, the Agent Skills format Claude Code and Codex write, is taken as it is.

![A SKILL.md saved with POST /v1/skills, then called as inferenceindex-0.1/skl_…](/docs/figures/skills.svg)

## Bring a SKILL.md

Send the file's text as `skill`. Nothing needs converting.

- **Name and description.** The frontmatter `name` and `description` become the skill's name and description. The rest is the instructions.
- **Steps.** The outermost numbered list is the steps. Numbered lines inside code fences and nested lists are not steps. Several numbered lists become one procedure, each step named by the heading above it. A file with no numbered list runs as one step.
- **One file.** Only the file itself is read, not the files it points to, such as `references/` or `scripts/`.
- **Size.** A skill can be up to 20,000 characters.

## Save one

```bash
curl https://api.inferenceindex.com/v1/skills \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "triage-ticket", "skill": "1. Read the ticket.\n2. Pick the queue.\n3. Draft the reply."}'
```

`name` can be left out when the skill names itself, with a frontmatter `name` or a `# Title`. Saving checks the skill, and the response has its id, `skl_…`.

| Call | What it does |
| --- | --- |
| `POST /v1/skills` with `{ "name", "skill" }` | Saves a new skill |
| `GET /v1/skills` | Lists your skills |
| `GET /v1/skills/:id?version=2` | Reads one, at a version if you give one |
| `POST /v1/skills/:id/versions` with `{ "skill" }` | Adds a version. A saved version never changes. |
| `DELETE /v1/skills/:id` | Archives it. It can't be called after that, and its versions are kept. |

A skill belongs to the account that saved it. Another account's skill answers `404`, the same as one that doesn't exist.

## Call it

Put the id in the model name: `inferenceindex-0.1/skl_…`, or `inferenceindex-0.1/skl_…@2` to pin version 2. Without a version, the current one runs.

```python
response = client.chat.completions.create(
    model="inferenceindex-0.1/skl_YOUR_SKILL_ID",
    messages=messages,
    tools=tools,
)
```

You can also name it in the body as `skill_id` and `skill_version` (`extra_body` in the OpenAI SDKs), or send the skill's text as `skill`. Agents that can only set headers can send `X-Skill-Id` and `X-Skill-Version`. Naming two different skills in one request is refused with `skill_conflict`.

Your system and developer messages become the run's instructions, and your user messages its request. Every saved skill is listed by `GET /v1/models`.

## Hints, scripts, and checks

A skill can also carry prepared responses and scripts. [Code mode](/docs/code-mode) is where those go: a `## Hints` block for wording, and a `## Scripts` block for writes the skill defines. Checks are the `## Checks` block below. Images on a run are on the [images](/docs/images) page.

## Checks

A `## Checks` section is a fenced JSON block keyed by step number, starting at 1. Each step's value is a list of checks. Code runs them. A step has not succeeded while a required check is still failing. The response lists them on `inferenceindex.checks`, and the [quickstart](/docs/quickstart) shows that object.

| Field | What it is |
| --- | --- |
| `id` | A name for the check. If you leave it out, it is `check_1`, `check_2`, and so on. |
| `required` | Default `true`. Set `false` and the step can still succeed while this check fails. |
| `onFailure` | `loop`, `reject`, `fail`, or `escalate`. Default `fail`. |
| `read` | A follow-up read: `tool`, optional `args`, and optional `expect`. |
| `schema` | A JSON schema for the result. |
| `status` | An HTTP status, or a list of them, from 100 to 599. |
| `verdict` | `true` asks for this step's own verdict once its other checks have passed. |

A check needs a `read`, a `schema`, a `status`, or `verdict` set to `true`. When `read` is set, `schema` and `status` apply to that read's result. Otherwise they apply to the step's own result.

`onFailure` says what happens when a required check fails:

- **`loop`.** The step is tried again, up to 2 further times. If it still fails, the run stops with outcome `fail`. If a write's outcome is uncertain, the write is not sent again and the outcome is `escalate`.
- **`reject`.** The run stops with outcome `rework`.
- **`fail`.** The run stops with outcome `fail`.
- **`escalate`.** The run stops with outcome `escalate`.

`read.args` values are literals, or `{ "from": "args", "field": "id" }` or `{ "from": "result", "field": "id" }` to copy from the step's call. `expect` is the fields the read must show. A dotted name reads a nested field. A list passes when any record in it matches.

````markdown
# Record a payment

Use when an invoice should be marked paid and the ledger should show that it was.

1. Read the invoice.
2. Mark the invoice paid.

## Checks

```json
{
  "2": [
    {
      "id": "landed",
      "required": true,
      "onFailure": "fail",
      "read": {
        "tool": "get_invoice",
        "args": { "id": { "from": "args", "field": "id" } },
        "expect": { "status": "paid" }
      }
    }
  ]
}
```
````

A step that only checks the call's own result can use `status` and `schema` instead of a read:

```json
{
  "1": [
    { "id": "http", "required": true, "onFailure": "fail", "status": 200 },
    {
      "id": "shape",
      "required": true,
      "onFailure": "fail",
      "schema": {
        "type": "object",
        "required": ["id", "status"],
        "properties": {
          "id": { "type": "string" },
          "status": { "type": "number" }
        }
      }
    }
  ]
}
```

## No skill yet

Send `"plan": true` in the body, with your tools and no skill named. A skill is written for the request from your tools, after reading what the request depends on, and the run follows it. Send `"plan": {"save": true}` to keep it as one of your skills, marked for review.

`plan.read_first` defaults to `true`: those reads happen first, as ordinary tool calls, and the skill is written from what they return. Set it to `false` to write the skill from the request alone. While those reads are still going out, `inferenceindex.plan.status` is `reading`.

`plan.reasoning` is how hard your fallback model reasons while it writes the skill. It defaults to `high`, whatever `reasoning_effort` says for the rest of the run. The efforts are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. The rest of the run follows `reasoning_effort`, which defaults to `none`.

Once the plan exists, `inferenceindex.plan` carries its `id` (`pln_…`), `name`, `status`, and `skill_id`. `status` is `pending`, `worked`, or `needs_work`.

| Call | What it does |
| --- | --- |
| `GET /v1/plans?status=pending` | Lists your plans. `status` is optional: `pending`, `worked`, or `needs_work`. |
| `GET /v1/plans/pln_…` | Reads one plan. Another account's plan is not found, the same as one that does not exist. |
| `POST /v1/feedback` with `{ "plan_id", "worked", "comment" }` | Says whether the plan did the job. `worked` is true or false. `comment` is optional, up to 4,000 characters. |

`GET /v1/plans` returns `{ "plans": [ { "id", "name", "status", "skill_id", "createdAt", "updatedAt" } ] }`.

`GET /v1/plans/pln_…` returns `id`, `name`, `body`, `sha256`, `request`, `toolNames`, `status`, `skillId`, `createdAt`, `updatedAt`, and `feedback`. Each feedback item is `worked`, `comment`, and `createdAt`.

`POST /v1/feedback` for a plan is `plan_id` with `worked`. Do not mix that with `run_id` and `completed` in the same body. The response is `{ "plan_id", "status" }`. A body that mixes them, or sends neither pair, is `400` with `invalid_body` and the message `Send run_id with completed, or plan_id with worked`. The run's own `completed` feedback is on the [quickstart](/docs/quickstart).

## Related

- [Code mode](/docs/code-mode)
- [Images](/docs/images)
- [Quickstart](/docs/quickstart)
- [How it works](/docs/how-it-works)
- [Fallback models](/docs/fallback-models)
