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

# Skills

> Create and manage versioned domain expertise that Atlas invokes during reasoning.

A skill is encoded domain expertise scoped to a user or group. Skills are reusable instructions Atlas draws on while reasoning, capturing how you or your team approach specific kinds of problems.

See [Adding a Personal Skill & System Memory](/guides/memories-and-skills) for a workflow guide.

## Endpoints

| Method   | Path                          | Description                     |
| -------- | ----------------------------- | ------------------------------- |
| `POST`   | `/skills`                     | Create a skill                  |
| `GET`    | `/skills`                     | List skills                     |
| `GET`    | `/skills/{skill_id}`          | Get a skill                     |
| `PATCH`  | `/skills/{skill_id}`          | Update a skill                  |
| `DELETE` | `/skills/{skill_id}`          | Delete a skill                  |
| `GET`    | `/skills/{skill_id}/versions` | List version history            |
| `POST`   | `/skills/{skill_id}/rollback` | Roll back to a previous version |

***

## Create a skill

`POST /skills`

**Request body:**

| Field           | Required | Type   | Description                                                                |
| --------------- | -------- | ------ | -------------------------------------------------------------------------- |
| `name`          | Yes      | string | Kebab-case identifier, 1–64 characters (e.g. `power-budget-analysis`)      |
| `description`   | Yes      | string | What the skill does, 1–1024 characters                                     |
| `power_command` | Yes      | string | Slash-command name Atlas recognizes. Kebab-case, no leading slash          |
| `instructions`  | Yes      | string | The procedure Atlas follows when this skill is active (markdown supported) |
| `scope`         | No       | string | `user` (personal, default) or `global` (org-wide)                          |
| `group_id`      | No       | UUID   | Group to scope this skill to (for group-scoped skills)                     |

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.atlas.arenaphysica.com/api/v1/skills" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "power-budget-analysis",
    "description": "Standard procedure for analyzing power budget violations.",
    "scope": "user",
    "power_command": "power-budget-analysis",
    "instructions": "When analyzing power issues:\n1. Check rail voltages against nominal spec.\n2. Identify load contributors sorted by draw.\n3. Flag any component exceeding 90% of its rated power.\n4. Check for inrush at startup."
  }'
```

**Response fields:**

| Field             | Type    | Nullable | Description                      |
| ----------------- | ------- | -------- | -------------------------------- |
| `uuid`            | UUID    | No       | Skill identifier                 |
| `name`            | string  | No       | Kebab-case name                  |
| `description`     | string  | No       | Skill description                |
| `scope`           | string  | No       | `user` or `global`               |
| `status`          | string  | No       | Approval status                  |
| `power_command`   | string  | No       | Command identifier               |
| `instructions`    | string  | No       | Skill content                    |
| `current_version` | integer | No       | Current version number           |
| `pending_version` | integer | Yes      | Version pending approval, if any |
| `created_by`      | string  | No       | Creator email                    |
| `group_id`        | UUID    | Yes      | Associated group                 |
| `job_id`          | UUID    | Yes      | Associated job, if any           |
| `created_at`      | string  | No       | ISO 8601 creation timestamp      |
| `updated_at`      | string  | No       | ISO 8601 last-update timestamp   |

**Example response:**

```json theme={null}
{
  "uuid": "e1f2a3b4-c5d6-7890-efab-901234567890",
  "name": "power-budget-analysis",
  "description": "Standard procedure for analyzing power budget violations.",
  "scope": "user",
  "status": "active",
  "power_command": "power-budget-analysis",
  "instructions": "When analyzing power issues:\n1. Check rail voltages against nominal spec.\n2. Identify load contributors sorted by draw.\n3. Flag any component exceeding 90% of its rated power.\n4. Check for inrush at startup.",
  "current_version": 1,
  "pending_version": null,
  "created_by": "engineer@example.com",
  "group_id": null,
  "job_id": null,
  "created_at": "2026-04-13T12:00:00.000000",
  "updated_at": "2026-04-13T12:00:00.000000"
}
```

***

## List skills

`GET /skills`

**Query parameters:**

| Parameter | Type   | Description                         |
| --------- | ------ | ----------------------------------- |
| `scope`   | string | Filter by scope: `user` or `global` |
| `status`  | string | Filter by approval status           |
| `search`  | string | Search by name or power command     |

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/skills" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns `{"items": [...], "count": N}` where each item is a skill object with the same fields as the [create response](#create-a-skill).

***

## Get a skill

`GET /skills/{skill_id}`

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/skills/$SKILL_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns a single skill object with the same fields as the [create response](#create-a-skill).

***

## Delete a skill

`DELETE /skills/{skill_id}`

**Example request:**

```bash theme={null}
curl -X DELETE "https://nokia.atlas.arenaphysica.com/api/v1/skills/$SKILL_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns **204 No Content**.

***

## Update a skill

`PATCH /skills/{skill_id}`

All fields are optional. Each update creates a new version.

| Field            | Type   | Description                                   |
| ---------------- | ------ | --------------------------------------------- |
| `name`           | string | New kebab-case name                           |
| `description`    | string | Updated description                           |
| `scope`          | string | `user` or `global`                            |
| `power_command`  | string | Updated command identifier                    |
| `instructions`   | string | Updated skill content                         |
| `change_summary` | string | Notes describing what changed in this version |

**Example request:**

```bash theme={null}
curl -X PATCH "https://nokia.atlas.arenaphysica.com/api/v1/skills/$SKILL_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "When analyzing power issues:\n1. Check rail voltages against nominal spec.\n2. Review thermal derating curves.\n3. Identify top load contributors.\n4. Flag components above 90% rated power.\n5. Check startup inrush.",
    "change_summary": "Added thermal derating step"
  }'
```

Returns the updated skill object with the same fields as the [create response](#create-a-skill).

***

## Version history and rollback

`GET /skills/{skill_id}/versions`

Returns all versions of a skill.

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/skills/$SKILL_ID/versions" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

**Response fields (array):**

| Field            | Type    | Description                   |
| ---------------- | ------- | ----------------------------- |
| `uuid`           | UUID    | Version identifier            |
| `version_number` | integer | Version number (1-indexed)    |
| `name`           | string  | Skill name at this version    |
| `description`    | string  | Description at this version   |
| `scope`          | string  | Scope at this version         |
| `power_command`  | string  | Power command at this version |
| `instructions`   | string  | Skill content at this version |
| `status`         | string  | Approval status               |
| `created_by`     | string  | Author email                  |
| `created_at`     | string  | ISO 8601 creation timestamp   |
| `change_summary` | string  | Notes describing what changed |

**Example response:**

```json theme={null}
[
  {
    "uuid": "f1a2b3c4-d5e6-7890-fabc-012345678901",
    "version_number": 2,
    "name": "power-budget-analysis",
    "description": "Standard procedure for analyzing power budget violations.",
    "scope": "user",
    "power_command": "power-budget-analysis",
    "instructions": "When analyzing power issues:\n1. Check rail voltages against nominal spec.\n2. Review thermal derating curves.\n3. Identify top load contributors.\n4. Flag components above 90% rated power.\n5. Check startup inrush.",
    "status": "active",
    "created_by": "engineer@example.com",
    "created_at": "2026-04-13T12:05:00.000000",
    "change_summary": "Added thermal derating step"
  },
  {
    "uuid": "e1f2a3b4-c5d6-7890-efab-901234567890",
    "version_number": 1,
    "name": "power-budget-analysis",
    "description": "Standard procedure for analyzing power budget violations.",
    "scope": "user",
    "power_command": "power-budget-analysis",
    "instructions": "When analyzing power issues:\n1. Check rail voltages against nominal spec.\n2. Identify load contributors sorted by draw.\n3. Flag any component exceeding 90% of its rated power.\n4. Check for inrush at startup.",
    "status": "active",
    "created_by": "engineer@example.com",
    "created_at": "2026-04-13T12:00:00.000000",
    "change_summary": null
  }
]
```

***

`POST /skills/{skill_id}/rollback`

Rolls back to a previous version.

**Request body:**

| Field            | Required | Type    | Description             |
| ---------------- | -------- | ------- | ----------------------- |
| `version_number` | Yes      | integer | Version to roll back to |

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.atlas.arenaphysica.com/api/v1/skills/$SKILL_ID/rollback" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version_number": 1}'
```

Returns the updated skill object with the same fields as the [create response](#create-a-skill), reflecting the rolled-back version.