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

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

Response

{
  "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

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

Response

{
  "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

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

Response

{
  "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

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

Response

{
  "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

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

cli/resources/skills/subresources/versions/index.md +443 −0 created

1# Versions

3## Create a new immutable skill version.

5`$ openai skills:versions create`

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

9Create a new immutable skill version.

11### Parameters

13- `--skill-id: string`

15 The identifier of the skill to version.

17- `--default: optional boolean`

19 Whether to set this version as the default.

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

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

25### Returns

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

29 - `id: string`

31 Unique identifier for the skill version.

33 - `created_at: number`

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

37 - `description: string`

39 Description of the skill version.

41 - `name: string`

43 Name of the skill version.

45 - `object: "skill.version"`

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

49 - `skill_id: string`

51 Identifier of the skill for this version.

53 - `version: string`

55 Version number for this skill.

57### Example

59```cli

60openai skills:versions create \

61 --api-key 'My API Key' \

62 --skill-id skill_123

63```

65#### Response

67```json

68{

69 "id": "id",

70 "created_at": 0,

71 "description": "description",

72 "name": "name",

73 "object": "skill.version",

74 "skill_id": "skill_id",

75 "version": "version"

76}

77```

79## List skill versions for a skill.

81`$ openai skills:versions list`

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

85List skill versions for a skill.

87### Parameters

89- `--skill-id: string`

91 The identifier of the skill.

93- `--after: optional string`

95 The skill version ID to start after.

97- `--limit: optional number`

99 Number of versions to retrieve.

100

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

102

103 Sort order of results by version number.

104

105### Returns

106

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

108

109 - `data: array of SkillVersion`

110

111 A list of items

112

113 - `id: string`

114

115 Unique identifier for the skill version.

116

117 - `created_at: number`

118

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

120

121 - `description: string`

122

123 Description of the skill version.

124

125 - `name: string`

126

127 Name of the skill version.

128

129 - `object: "skill.version"`

130

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

132

133 - `skill_id: string`

134

135 Identifier of the skill for this version.

136

137 - `version: string`

138

139 Version number for this skill.

140

141 - `first_id: string`

142

143 The ID of the first item in the list.

144

145 - `has_more: boolean`

146

147 Whether there are more items available.

148

149 - `last_id: string`

150

151 The ID of the last item in the list.

152

153 - `object: "list"`

154

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

156

157### Example

158

159```cli

160openai skills:versions list \

161 --api-key 'My API Key' \

162 --skill-id skill_123

163```

164

165#### Response

166

167```json

168{

169 "data": [

170 {

171 "id": "id",

172 "created_at": 0,

173 "description": "description",

174 "name": "name",

175 "object": "skill.version",

176 "skill_id": "skill_id",

177 "version": "version"

178 }

179 ],

180 "first_id": "first_id",

181 "has_more": true,

182 "last_id": "last_id",

183 "object": "list"

184}

185```

186

187## Get a specific skill version.

188

189`$ openai skills:versions retrieve`

190

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

192

193Get a specific skill version.

194

195### Parameters

196

197- `--skill-id: string`

198

199 The identifier of the skill.

200

201- `--version: string`

202

203 The version number to retrieve.

204

205### Returns

206

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

208

209 - `id: string`

210

211 Unique identifier for the skill version.

212

213 - `created_at: number`

214

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

216

217 - `description: string`

218

219 Description of the skill version.

220

221 - `name: string`

222

223 Name of the skill version.

224

225 - `object: "skill.version"`

226

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

228

229 - `skill_id: string`

230

231 Identifier of the skill for this version.

232

233 - `version: string`

234

235 Version number for this skill.

236

237### Example

238

239```cli

240openai skills:versions retrieve \

241 --api-key 'My API Key' \

242 --skill-id skill_123 \

243 --version version

244```

245

246#### Response

247

248```json

249{

250 "id": "id",

251 "created_at": 0,

252 "description": "description",

253 "name": "name",

254 "object": "skill.version",

255 "skill_id": "skill_id",

256 "version": "version"

257}

258```

259

260## Delete a skill version.

261

262`$ openai skills:versions delete`

263

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

265

266Delete a skill version.

267

268### Parameters

269

270- `--skill-id: string`

271

272 The identifier of the skill.

273

274- `--version: string`

275

276 The skill version number.

277

278### Returns

279

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

281

282 - `id: string`

283

284 - `deleted: boolean`

285

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

287

288 - `version: string`

289

290 The deleted skill version.

291

292### Example

293

294```cli

295openai skills:versions delete \

296 --api-key 'My API Key' \

297 --skill-id skill_123 \

298 --version version

299```

300

301#### Response

302

303```json

304{

305 "id": "id",

306 "deleted": true,

307 "object": "skill.version.deleted",

308 "version": "version"

309}

310```

311

312## Domain Types

313

314### Deleted Skill Version

315

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

317

318 - `id: string`

319

320 - `deleted: boolean`

321

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

323

324 - `version: string`

325

326 The deleted skill version.

327

328### Skill Version

329

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

331

332 - `id: string`

333

334 Unique identifier for the skill version.

335

336 - `created_at: number`

337

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

339

340 - `description: string`

341

342 Description of the skill version.

343

344 - `name: string`

345

346 Name of the skill version.

347

348 - `object: "skill.version"`

349

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

351

352 - `skill_id: string`

353

354 Identifier of the skill for this version.

355

356 - `version: string`

357

358 Version number for this skill.

359

360### Skill Version List

361

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

363

364 - `data: array of SkillVersion`

365

366 A list of items

367

368 - `id: string`

369

370 Unique identifier for the skill version.

371

372 - `created_at: number`

373

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

375

376 - `description: string`

377

378 Description of the skill version.

379

380 - `name: string`

381

382 Name of the skill version.

383

384 - `object: "skill.version"`

385

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

387

388 - `skill_id: string`

389

390 Identifier of the skill for this version.

391

392 - `version: string`

393

394 Version number for this skill.

395

396 - `first_id: string`

397

398 The ID of the first item in the list.

399

400 - `has_more: boolean`

401

402 Whether there are more items available.

403

404 - `last_id: string`

405

406 The ID of the last item in the list.

407

408 - `object: "list"`

409

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

411

412# Content

413

414## Download a skill version zip bundle.

415

416`$ openai skills:versions:content retrieve`

417

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

419

420Download a skill version zip bundle.

421

422### Parameters

423

424- `--skill-id: string`

425

426 The identifier of the skill.

427

428- `--version: string`

429

430 The skill version number.

431

432### Returns

433

434- `unnamed_schema_5: file path`

435

436### Example

437

438```cli

439openai skills:versions:content retrieve \

440 --api-key 'My API Key' \

441 --skill-id skill_123 \

442 --version version

443```

cli/resources/skills/subresources/versions/index.md 2026-05-05 23:00 UTC to 2026-05-07 21:57 UTC

Versions

Create a new immutable skill version.

Parameters

Returns

Example

Response

List skill versions for a skill.

Parameters

Returns

Example

Response

Get a specific skill version.

Parameters

Returns

Example

Response

Delete a skill version.

Parameters

Returns

Example

Response

Domain Types

Deleted Skill Version

Skill Version

Skill Version List

Content

Download a skill version zip bundle.

Parameters

Returns

Example