# Skills

## Create a new skill.

`$ openai skills create`

**post** `/skills`

Create a new skill.

### Parameters

- `--files: optional array of string or string`

  Skill files to upload (directory upload) or a single zip file.

### Returns

- `skill: object { id, created_at, default_version, 4 more }`

  - `id: string`

    Unique identifier for the skill.

  - `created_at: number`

    Unix timestamp (seconds) for when the skill was created.

  - `default_version: string`

    Default version for the skill.

  - `description: string`

    Description of the skill.

  - `latest_version: string`

    Latest version for the skill.

  - `name: string`

    Name of the skill.

  - `object: "skill"`

    The object type, which is `skill`.

### Example

```cli
openai skills create \
  --api-key 'My API Key'
```

#### Response

```json
{
  "id": "id",
  "created_at": 0,
  "default_version": "default_version",
  "description": "description",
  "latest_version": "latest_version",
  "name": "name",
  "object": "skill"
}
```

## List all skills for the current project.

`$ openai skills list`

**get** `/skills`

List all skills for the current project.

### Parameters

- `--after: optional string`

  Identifier for the last item from the previous pagination request

- `--limit: optional number`

  Number of items to retrieve

- `--order: optional "asc" or "desc"`

  Sort order of results by timestamp. Use `asc` for ascending order or `desc` for descending order.

### Returns

- `skill_list: object { data, first_id, has_more, 2 more }`

  - `data: array of Skill`

    A list of items

    - `id: string`

      Unique identifier for the skill.

    - `created_at: number`

      Unix timestamp (seconds) for when the skill was created.

    - `default_version: string`

      Default version for the skill.

    - `description: string`

      Description of the skill.

    - `latest_version: string`

      Latest version for the skill.

    - `name: string`

      Name of the skill.

    - `object: "skill"`

      The object type, which is `skill`.

  - `first_id: string`

    The ID of the first item in the list.

  - `has_more: boolean`

    Whether there are more items available.

  - `last_id: string`

    The ID of the last item in the list.

  - `object: "list"`

    The type of object returned, must be `list`.

### Example

```cli
openai skills list \
  --api-key 'My API Key'
```

#### Response

```json
{
  "data": [
    {
      "id": "id",
      "created_at": 0,
      "default_version": "default_version",
      "description": "description",
      "latest_version": "latest_version",
      "name": "name",
      "object": "skill"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}
```

## Get a skill by its ID.

`$ openai skills retrieve`

**get** `/skills/{skill_id}`

Get a skill by its ID.

### Parameters

- `--skill-id: string`

  The identifier of the skill to retrieve.

### Returns

- `skill: object { id, created_at, default_version, 4 more }`

  - `id: string`

    Unique identifier for the skill.

  - `created_at: number`

    Unix timestamp (seconds) for when the skill was created.

  - `default_version: string`

    Default version for the skill.

  - `description: string`

    Description of the skill.

  - `latest_version: string`

    Latest version for the skill.

  - `name: string`

    Name of the skill.

  - `object: "skill"`

    The object type, which is `skill`.

### Example

```cli
openai skills retrieve \
  --api-key 'My API Key' \
  --skill-id skill_123
```

#### Response

```json
{
  "id": "id",
  "created_at": 0,
  "default_version": "default_version",
  "description": "description",
  "latest_version": "latest_version",
  "name": "name",
  "object": "skill"
}
```

## Update the default version pointer for a skill.

`$ openai skills update`

**post** `/skills/{skill_id}`

Update the default version pointer for a skill.

### Parameters

- `--skill-id: string`

  The identifier of the skill.

- `--default-version: string`

  The skill version number to set as default.

### Returns

- `skill: object { id, created_at, default_version, 4 more }`

  - `id: string`

    Unique identifier for the skill.

  - `created_at: number`

    Unix timestamp (seconds) for when the skill was created.

  - `default_version: string`

    Default version for the skill.

  - `description: string`

    Description of the skill.

  - `latest_version: string`

    Latest version for the skill.

  - `name: string`

    Name of the skill.

  - `object: "skill"`

    The object type, which is `skill`.

### Example

```cli
openai skills update \
  --api-key 'My API Key' \
  --skill-id skill_123 \
  --default-version default_version
```

#### Response

```json
{
  "id": "id",
  "created_at": 0,
  "default_version": "default_version",
  "description": "description",
  "latest_version": "latest_version",
  "name": "name",
  "object": "skill"
}
```

## Delete a skill by its ID.

`$ openai skills delete`

**delete** `/skills/{skill_id}`

Delete a skill by its ID.

### Parameters

- `--skill-id: string`

  The identifier of the skill to delete.

### Returns

- `deleted_skill: object { id, deleted, object }`

  - `id: string`

  - `deleted: boolean`

  - `object: "skill.deleted"`

### Example

```cli
openai skills delete \
  --api-key 'My API Key' \
  --skill-id skill_123
```

#### Response

```json
{
  "id": "id",
  "deleted": true,
  "object": "skill.deleted"
}
```

## Domain Types

### Deleted Skill

- `deleted_skill: object { id, deleted, object }`

  - `id: string`

  - `deleted: boolean`

  - `object: "skill.deleted"`

### Skill

- `skill: object { id, created_at, default_version, 4 more }`

  - `id: string`

    Unique identifier for the skill.

  - `created_at: number`

    Unix timestamp (seconds) for when the skill was created.

  - `default_version: string`

    Default version for the skill.

  - `description: string`

    Description of the skill.

  - `latest_version: string`

    Latest version for the skill.

  - `name: string`

    Name of the skill.

  - `object: "skill"`

    The object type, which is `skill`.

### Skill List

- `skill_list: object { data, first_id, has_more, 2 more }`

  - `data: array of Skill`

    A list of items

    - `id: string`

      Unique identifier for the skill.

    - `created_at: number`

      Unix timestamp (seconds) for when the skill was created.

    - `default_version: string`

      Default version for the skill.

    - `description: string`

      Description of the skill.

    - `latest_version: string`

      Latest version for the skill.

    - `name: string`

      Name of the skill.

    - `object: "skill"`

      The object type, which is `skill`.

  - `first_id: string`

    The ID of the first item in the list.

  - `has_more: boolean`

    Whether there are more items available.

  - `last_id: string`

    The ID of the last item in the list.

  - `object: "list"`

    The type of object returned, must be `list`.

# Content

## Download a skill zip bundle by its ID.

`$ openai skills:content retrieve`

**get** `/skills/{skill_id}/content`

Download a skill zip bundle by its ID.

### Parameters

- `--skill-id: string`

  The identifier of the skill to download.

### Returns

- `unnamed_schema_4: file path`

### Example

```cli
openai skills:content retrieve \
  --api-key 'My API Key' \
  --skill-id skill_123
```

# Versions

## Create a new immutable skill version.

`$ openai skills:versions create`

**post** `/skills/{skill_id}/versions`

Create a new immutable skill version.

### Parameters

- `--skill-id: string`

  The identifier of the skill to version.

- `--default: optional boolean`

  Whether to set this version as the default.

- `--files: optional array of string or string`

  Skill files to upload (directory upload) or a single zip file.

### Returns

- `skill_version: object { id, created_at, description, 4 more }`

  - `id: string`

    Unique identifier for the skill version.

  - `created_at: number`

    Unix timestamp (seconds) for when the version was created.

  - `description: string`

    Description of the skill version.

  - `name: string`

    Name of the skill version.

  - `object: "skill.version"`

    The object type, which is `skill.version`.

  - `skill_id: string`

    Identifier of the skill for this version.

  - `version: string`

    Version number for this skill.

### Example

```cli
openai skills:versions create \
  --api-key 'My API Key' \
  --skill-id skill_123
```

#### Response

```json
{
  "id": "id",
  "created_at": 0,
  "description": "description",
  "name": "name",
  "object": "skill.version",
  "skill_id": "skill_id",
  "version": "version"
}
```

## List skill versions for a skill.

`$ openai skills:versions list`

**get** `/skills/{skill_id}/versions`

List skill versions for a skill.

### Parameters

- `--skill-id: string`

  The identifier of the skill.

- `--after: optional string`

  The skill version ID to start after.

- `--limit: optional number`

  Number of versions to retrieve.

- `--order: optional "asc" or "desc"`

  Sort order of results by version number.

### Returns

- `skill_version_list: object { data, first_id, has_more, 2 more }`

  - `data: array of SkillVersion`

    A list of items

    - `id: string`

      Unique identifier for the skill version.

    - `created_at: number`

      Unix timestamp (seconds) for when the version was created.

    - `description: string`

      Description of the skill version.

    - `name: string`

      Name of the skill version.

    - `object: "skill.version"`

      The object type, which is `skill.version`.

    - `skill_id: string`

      Identifier of the skill for this version.

    - `version: string`

      Version number for this skill.

  - `first_id: string`

    The ID of the first item in the list.

  - `has_more: boolean`

    Whether there are more items available.

  - `last_id: string`

    The ID of the last item in the list.

  - `object: "list"`

    The type of object returned, must be `list`.

### Example

```cli
openai skills:versions list \
  --api-key 'My API Key' \
  --skill-id skill_123
```

#### Response

```json
{
  "data": [
    {
      "id": "id",
      "created_at": 0,
      "description": "description",
      "name": "name",
      "object": "skill.version",
      "skill_id": "skill_id",
      "version": "version"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}
```

## Get a specific skill version.

`$ openai skills:versions retrieve`

**get** `/skills/{skill_id}/versions/{version}`

Get a specific skill version.

### Parameters

- `--skill-id: string`

  The identifier of the skill.

- `--version: string`

  The version number to retrieve.

### Returns

- `skill_version: object { id, created_at, description, 4 more }`

  - `id: string`

    Unique identifier for the skill version.

  - `created_at: number`

    Unix timestamp (seconds) for when the version was created.

  - `description: string`

    Description of the skill version.

  - `name: string`

    Name of the skill version.

  - `object: "skill.version"`

    The object type, which is `skill.version`.

  - `skill_id: string`

    Identifier of the skill for this version.

  - `version: string`

    Version number for this skill.

### Example

```cli
openai skills:versions retrieve \
  --api-key 'My API Key' \
  --skill-id skill_123 \
  --version version
```

#### Response

```json
{
  "id": "id",
  "created_at": 0,
  "description": "description",
  "name": "name",
  "object": "skill.version",
  "skill_id": "skill_id",
  "version": "version"
}
```

## Delete a skill version.

`$ openai skills:versions delete`

**delete** `/skills/{skill_id}/versions/{version}`

Delete a skill version.

### Parameters

- `--skill-id: string`

  The identifier of the skill.

- `--version: string`

  The skill version number.

### Returns

- `deleted_skill_version: object { id, deleted, object, version }`

  - `id: string`

  - `deleted: boolean`

  - `object: "skill.version.deleted"`

  - `version: string`

    The deleted skill version.

### Example

```cli
openai skills:versions delete \
  --api-key 'My API Key' \
  --skill-id skill_123 \
  --version version
```

#### Response

```json
{
  "id": "id",
  "deleted": true,
  "object": "skill.version.deleted",
  "version": "version"
}
```

## Domain Types

### Deleted Skill Version

- `deleted_skill_version: object { id, deleted, object, version }`

  - `id: string`

  - `deleted: boolean`

  - `object: "skill.version.deleted"`

  - `version: string`

    The deleted skill version.

### Skill Version

- `skill_version: object { id, created_at, description, 4 more }`

  - `id: string`

    Unique identifier for the skill version.

  - `created_at: number`

    Unix timestamp (seconds) for when the version was created.

  - `description: string`

    Description of the skill version.

  - `name: string`

    Name of the skill version.

  - `object: "skill.version"`

    The object type, which is `skill.version`.

  - `skill_id: string`

    Identifier of the skill for this version.

  - `version: string`

    Version number for this skill.

### Skill Version List

- `skill_version_list: object { data, first_id, has_more, 2 more }`

  - `data: array of SkillVersion`

    A list of items

    - `id: string`

      Unique identifier for the skill version.

    - `created_at: number`

      Unix timestamp (seconds) for when the version was created.

    - `description: string`

      Description of the skill version.

    - `name: string`

      Name of the skill version.

    - `object: "skill.version"`

      The object type, which is `skill.version`.

    - `skill_id: string`

      Identifier of the skill for this version.

    - `version: string`

      Version number for this skill.

  - `first_id: string`

    The ID of the first item in the list.

  - `has_more: boolean`

    Whether there are more items available.

  - `last_id: string`

    The ID of the last item in the list.

  - `object: "list"`

    The type of object returned, must be `list`.

# Content

## Download a skill version zip bundle.

`$ openai skills:versions:content retrieve`

**get** `/skills/{skill_id}/versions/{version}/content`

Download a skill version zip bundle.

### Parameters

- `--skill-id: string`

  The identifier of the skill.

- `--version: string`

  The skill version number.

### Returns

- `unnamed_schema_5: file path`

### Example

```cli
openai skills:versions:content retrieve \
  --api-key 'My API Key' \
  --skill-id skill_123 \
  --version version
```