> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolvingmachines.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Evolve has two products behind one API key. Edith answers questions about an agent trajectory over HTTP: `POST https://api.evolvingmachines.ai/v1/decisions`. Evaluations run coding agents on tasks in cloud sandboxes, through the `evolve` CLI, the Python and TypeScript SDKs, or HTTP.
> A person creates the key at https://dashboard.evolvingmachines.ai/api-keys. Read it from `EVOLVE_API_KEY`; never ask for it in chat or write it to a file.
> Install the CLI with `npm install -g @evolvingmachines/evolve`, then confirm the connection with `evolve auth status`.
> The CLI carries the manual for its own version. `evolve skills get evals` prints the index and `evolve skills get evals <page>` prints one page, for example `evolve skills get evals cli-reference/run`. When the installed CLI is older than this site, follow the installed manual.
> Commands take `--help` for their options and `--json` for machine-readable output. Evaluations spend credits: start with one task and set `--max-trial-spend`.

# Skills HTTP API

> Upload skill folders and attach them to an evaluation's agents.

Upload skill folders to Evolve, then attach their returned `upload:<id>` references to a job's agent arms. These uploads are the skills an evaluated agent receives, separate from the CLI's documentation skill.

Examples reuse [connection setup](https://docs.evolvingmachines.ai/api-reference/index.md#connect). Create `skill.tar.gz` from a skill folder containing `SKILL.md`, with that file at the archive root:

```bash theme={"dark"}
curl -sS "$API/api/skills" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -F 'archive=@skill.tar.gz' \
  -F 'name=my-skill'
```

Success returns `201` with `{ "skills": [...] }`, containing one or more `SkillUpload` records. Use a returned `id`, not the folder name, in an `upload:<id>` reference.

## Routes

| Method and path | Input | Success |
| - | - | - |
| `POST /api/skills` | Multipart fields below | `201`, object with a `skills` array |
| `GET /api/skills` | Optional `scope`, `limit`, `cursor`, `sortField`, `sortDirection` | `200 SkillUploadPage` |
| `GET /api/skills/{id}` | Upload id or `name:<skill-name>` | `200 SkillUpload` plus `skill_md` |
| `DELETE /api/skills/{id}` | Returned upload id | `204`, no body |

`scope` is `my` (default), `shared`, or `org`. `sortField` accepts `name`, `size`, or `uploaded`; `sortDirection` accepts `asc` or `desc`. Keep sorting unchanged while [paging](https://docs.evolvingmachines.ai/api-reference/index.md#pagination).

## Upload fields

| Multipart field | Required | Meaning |
| - | - | - |
| `archive` | Yes | Gzipped skill folder or directory of skill folders |
| `name` | For a root skill | Required when `SKILL.md` is at the archive root; ignored when child folders name the skills |
| `org` | No | Organization slug or id; requires membership; defaults to your personal organization |

`name` accepts letters, digits, `.`, `_`, and `-`, up to 100 characters. For multiple skills, put each skill in its own top-level folder with its own `SKILL.md`.

Uploading the same name and content reuses its record. Different content under the same name creates a new record and makes it the current `name:<skill-name>` reference. Existing `upload:<id>` references remain fixed. An existing identical record cannot be moved to another organization by reuploading it with a different `org`.

## Read and remove

Set `SKILL_ID` from an upload or list response:

```bash theme={"dark"}
curl -sS "$API/api/skills/$SKILL_ID" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"
```

The response includes metadata and `skill_md`, which is `null` when the text cannot be read. See [skill methods](https://docs.evolvingmachines.ai/sdk-reference/methods/skills.md) for the metadata fields.

GET also accepts `name:my-skill` to read your current upload for that name. Name lookup is limited to your own skills; organization members can read shared records by upload id.

```bash theme={"dark"}
curl -sS -X DELETE "$API/api/skills/$SKILL_ID" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"
```

Only the creator can delete an upload, and DELETE requires its record id, not a name reference. A `QUEUED`, `RUNNING`, or `CANCELLING` job referencing the upload prevents deletion with `409 skill_in_use`. Wait for that job to finish, or cancel it and wait until it settles.

For an agent arm, add the reference to its `skills` array:

```json theme={"dark"}
{
  "name": "codex",
  "model_name": "gpt-6-luna",
  "skills": ["upload:YOUR_SKILL_ID"]
}
```

This is an arm fragment, not a complete job request. Replace `YOUR_SKILL_ID`, then include the arm in [job creation](https://docs.evolvingmachines.ai/api-reference/jobs.md#create-a-job).

## Errors

Invalid archives, missing skill files, or an unsupported name are refused. Unknown upload ids return `404 skill_not_found`. Consult the [skill error codes](https://docs.evolvingmachines.ai/sdk-reference/error-codes.md#skills) and use `GET /api/meta` for current upload limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.