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

# The Skill object

> A company skill: identity, description, usage across careers and people, versions and activity

<Info>
  **Quick Summary:** A skill is a company-level definition. Its configuration *on a career* (benchmark, Required status, per-level activation) belongs to the [Career](/api-docs/resources/career) resource, not here.
</Info>

## Attributes

| Field             | Type           | Description                                                                                                                         |
| ----------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | string         | Opaque skill id                                                                                                                     |
| `name`            | string         | Skill name                                                                                                                          |
| `description`     | string \| null | Description                                                                                                                         |
| `isCertification` | boolean        | Whether the skill is a certification. Read-only — creates never set it                                                              |
| `isArchived`      | boolean        | Whether the skill is archived. Archived skills leave the default library listing but keep their history — see Retirement and delete |

```json theme={null}
{
  "id": "63",
  "name": "Welding",
  "description": "MIG and TIG welding.",
  "isCertification": false,
  "isArchived": false
}
```

List entries (`GET /api/v1/skills`) additionally carry a `usage` object:

| Field                        | Type    | Description                                                                                                                   |
| ---------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `usage.careers`              | array   | References `{ id, name }` to every career that **includes** the skill — attached directly or under a section, Required or not |
| `usage.peopleCount`          | integer | How many active people hold the skill, directly or through a career that includes it                                          |
| `usage.trainingDatesEnabled` | boolean | Whether any career including the skill has training dates enabled                                                             |

## Versions and activity

* `GET /api/v1/skills/{id}/versions` — every name/description snapshot, who edited it, when, an optional change note, and whether it is the baseline entry written when the skill was created.
* `GET /api/v1/skills/{id}/activity` — a **version log, not a change feed**. Exactly three event types are ever emitted: `baseline` (skill created), `version_created` (name or description changed, linked to its version entry via `versionId`), and `renew_training` (with `affectedUserCount` and `renewalOption`). A request approval, a career adding or removing the skill, and a benchmark or Required-status change produce **no** entry here — unlike the [career activity feed](/api-docs/resources/career), which records roughly forty event types.

## Retirement and delete

Two lanes, both reversible in spirit — prefer archive:

* `POST /api/v1/skills/{id}/archive` and `POST /api/v1/skills/{id}/unarchive` — the retirement path. An archived skill leaves the default library listing but keeps every grade, training and history row, stays readable by id, and can be brought back.
* `DELETE /api/v1/skills/{id}` — a **soft** delete: career attachments, grades and history are preserved as historic data, but the skill leaves every listing, filter and read. When the skill is attached to careers or held by people the call refuses with a [409 conflict](/api-docs/errors/conflict) carrying `dependencies` counts; retry with `?confirm=true` to proceed. A skill nothing references (a mistyped creation, say) deletes without ceremony.

A deleted skill answers [404](/api-docs/errors/not-found) on every read from that point on.