Skip to content

Commit d2edcb3

Browse files
varshaprasad96claude
varshaprasad96
and
claude
authored
feat(skills): add Skills API surface, data models, and provider registry (#5901)
# What does this PR do? Add the API surface for the Skills API (/v1alpha/skills), conforming to the OpenAI Skills API for managing versioned skill bundles. Refs: #5891 <!-- Provide a short summary of what this PR does and why. Link to relevant issues if applicable. --> <!-- If resolving an issue, uncomment and update the line below --> <!-- Closes #[issue-number] --> ## Test Plan <!-- Describe the tests you ran to verify your changes with result summaries. *Provide clear instructions so the plan can be easily re-executed.* --> <!-- For API changes, include: 1. A testing script (Python, curl, etc.) that exercises the new/modified endpoints 2. The output from running your script Example: ```python ... ... ``` Output: ``` <paste actual output here> ``` --> --------- Signed-off-by: Varsha Prasad Narsing <vnarsing@redhat.com> Signed-off-by: Varsha Prasad Narsing <varshaprasad96@gmail.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent b96329c commit d2edcb3

15 files changed

Lines changed: 1732 additions & 0 deletions

File tree

‎client-sdks/stainless/openapi.yml‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14632,6 +14632,7 @@ components:
1463214632
- connectors
1463314633
- messages
1463414634
- interactions
14635+
- skills
1463514636
- inspect
1463614637
- admin
1463714638
title: Api
@@ -16030,6 +16031,278 @@ components:
1603016031
- prompt_id
1603116032
title: DeletePromptRequest
1603216033
type: object
16034+
SkillVersion:
16035+
description: A specific version of a skill. Matches OpenAI SkillVersion wire format.
16036+
properties:
16037+
id:
16038+
description: Unique identifier for this version
16039+
title: Id
16040+
type: string
16041+
created_at:
16042+
description: Unix timestamp when this version was created
16043+
title: Created At
16044+
type: integer
16045+
description:
16046+
description: Description of the skill version
16047+
title: Description
16048+
type: string
16049+
name:
16050+
description: Name of the skill version
16051+
title: Name
16052+
type: string
16053+
object:
16054+
title: Object
16055+
type: string
16056+
enum:
16057+
- skill.version
16058+
skill_id:
16059+
description: ID of the parent skill
16060+
title: Skill Id
16061+
type: string
16062+
version:
16063+
description: Version number as a string
16064+
title: Version
16065+
type: string
16066+
required:
16067+
- id
16068+
- created_at
16069+
- description
16070+
- name
16071+
- skill_id
16072+
- version
16073+
title: SkillVersion
16074+
type: object
16075+
Skill:
16076+
description: A skill resource. Matches OpenAI Skill wire format.
16077+
properties:
16078+
id:
16079+
description: Unique identifier for the skill
16080+
title: Id
16081+
type: string
16082+
created_at:
16083+
description: Unix timestamp when the skill was created
16084+
title: Created At
16085+
type: integer
16086+
default_version:
16087+
default: '1'
16088+
description: Version used when no version is specified
16089+
title: Default Version
16090+
type: string
16091+
description:
16092+
description: Description of what the skill does
16093+
title: Description
16094+
type: string
16095+
latest_version:
16096+
default: '1'
16097+
description: Most recently uploaded version number
16098+
title: Latest Version
16099+
type: string
16100+
name:
16101+
description: Human-readable name from SKILL.md frontmatter
16102+
title: Name
16103+
type: string
16104+
object:
16105+
title: Object
16106+
type: string
16107+
enum:
16108+
- skill
16109+
required:
16110+
- id
16111+
- created_at
16112+
- description
16113+
- name
16114+
title: Skill
16115+
type: object
16116+
SkillDeleteResponse:
16117+
description: Response from deleting a skill. Matches OpenAI DeletedSkill wire format.
16118+
properties:
16119+
id:
16120+
description: ID of the deleted skill
16121+
title: Id
16122+
type: string
16123+
deleted:
16124+
default: true
16125+
description: Whether the skill was successfully deleted
16126+
title: Deleted
16127+
type: boolean
16128+
object:
16129+
title: Object
16130+
type: string
16131+
enum:
16132+
- skill.deleted
16133+
required:
16134+
- id
16135+
title: SkillDeleteResponse
16136+
type: object
16137+
SkillVersionDeleteResponse:
16138+
description: Response from deleting a skill version. Matches OpenAI DeletedSkillVersion wire format.
16139+
properties:
16140+
id:
16141+
description: ID of the deleted skill
16142+
title: Id
16143+
type: string
16144+
deleted:
16145+
default: true
16146+
description: Whether the version was successfully deleted
16147+
title: Deleted
16148+
type: boolean
16149+
object:
16150+
title: Object
16151+
type: string
16152+
enum:
16153+
- skill.version.deleted
16154+
version:
16155+
description: Version that was deleted
16156+
title: Version
16157+
type: string
16158+
required:
16159+
- id
16160+
- version
16161+
title: SkillVersionDeleteResponse
16162+
type: object
16163+
SkillVersionCreateRequest:
16164+
description: Request to create a new skill version. Matches OpenAI VersionCreateParams.
16165+
properties:
16166+
default:
16167+
type: boolean
16168+
default: false
16169+
description: Whether to set this version as the default
16170+
title: Default
16171+
title: SkillVersionCreateRequest
16172+
type: object
16173+
SkillUpdateRequest:
16174+
description: Request to update a skill's default version.
16175+
properties:
16176+
default_version:
16177+
description: Version number to set as the default
16178+
title: Default Version
16179+
type: string
16180+
required:
16181+
- default_version
16182+
title: SkillUpdateRequest
16183+
type: object
16184+
ListSkillsRequest:
16185+
description: Request parameters for listing skills.
16186+
properties:
16187+
after:
16188+
anyOf:
16189+
- type: string
16190+
- type: 'null'
16191+
description: Cursor for pagination
16192+
nullable: true
16193+
limit:
16194+
default: 20
16195+
description: Maximum number of results
16196+
maximum: 100
16197+
minimum: 1
16198+
title: Limit
16199+
type: integer
16200+
order:
16201+
default: desc
16202+
description: Sort order by created_at
16203+
enum:
16204+
- asc
16205+
- desc
16206+
title: Order
16207+
type: string
16208+
title: ListSkillsRequest
16209+
type: object
16210+
ListSkillsResponse:
16211+
description: Response from listing skills.
16212+
properties:
16213+
object:
16214+
title: Object
16215+
type: string
16216+
enum:
16217+
- list
16218+
data:
16219+
description: List of skill objects
16220+
items:
16221+
$ref: '#/components/schemas/Skill'
16222+
title: Data
16223+
type: array
16224+
has_more:
16225+
default: false
16226+
description: Whether there are more results
16227+
title: Has More
16228+
type: boolean
16229+
first_id:
16230+
anyOf:
16231+
- type: string
16232+
- type: 'null'
16233+
description: ID of the first item in the list
16234+
nullable: true
16235+
last_id:
16236+
anyOf:
16237+
- type: string
16238+
- type: 'null'
16239+
description: ID of the last item in the list
16240+
nullable: true
16241+
required:
16242+
- data
16243+
title: ListSkillsResponse
16244+
type: object
16245+
ListSkillVersionsRequest:
16246+
description: Request parameters for listing skill versions.
16247+
properties:
16248+
after:
16249+
anyOf:
16250+
- type: string
16251+
- type: 'null'
16252+
description: Cursor for pagination
16253+
nullable: true
16254+
limit:
16255+
default: 20
16256+
description: Maximum number of results
16257+
maximum: 100
16258+
minimum: 1
16259+
title: Limit
16260+
type: integer
16261+
order:
16262+
default: desc
16263+
description: Sort order by version
16264+
enum:
16265+
- asc
16266+
- desc
16267+
title: Order
16268+
type: string
16269+
title: ListSkillVersionsRequest
16270+
type: object
16271+
ListSkillVersionsResponse:
16272+
description: Response from listing skill versions.
16273+
properties:
16274+
object:
16275+
title: Object
16276+
type: string
16277+
enum:
16278+
- list
16279+
data:
16280+
description: List of skill version objects
16281+
items:
16282+
$ref: '#/components/schemas/SkillVersion'
16283+
title: Data
16284+
type: array
16285+
has_more:
16286+
default: false
16287+
description: Whether there are more results
16288+
title: Has More
16289+
type: boolean
16290+
first_id:
16291+
anyOf:
16292+
- type: string
16293+
- type: 'null'
16294+
description: ID of the first item in the list
16295+
nullable: true
16296+
last_id:
16297+
anyOf:
16298+
- type: string
16299+
- type: 'null'
16300+
description: ID of the last item in the list
16301+
nullable: true
16302+
required:
16303+
- data
16304+
title: ListSkillVersionsResponse
16305+
type: object
1603316306
OpenAIResponseMessageOutputUnion:
1603416307
anyOf:
1603516308
- oneOf:

‎docs/docs/providers/skills/index.mdx‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
description: |
3+
Skills API for managing versioned skill bundles.
4+
5+
Skills are zip archives containing a SKILL.md manifest and supporting files.
6+
Conforms to the OpenAI Skills API wire format.
7+
sidebar_label: Skills
8+
title: Skills
9+
---
10+
11+
# Skills
12+
13+
## Overview
14+
15+
Skills API for managing versioned skill bundles.
16+
17+
Skills are zip archives containing a SKILL.md manifest and supporting files.
18+
Conforms to the OpenAI Skills API wire format.
19+
20+
This section contains documentation for all available providers for the **skills** API.

‎docs/docs/providers/skills/inline_builtin.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
description: "Built-in skills provider using Files API for bundle storage."
3+
sidebar_label: Builtin
4+
title: inline::builtin
5+
---
6+
7+
# inline::builtin
8+
9+
## Description
10+
11+
Built-in skills provider using Files API for bundle storage.
12+
13+
## Configuration
14+
15+
| Field | Type | Required | Default | Description |
16+
|-------|------|----------|---------|-------------|
17+
| `persistence` | `KVStoreReference` | No | | KV store reference for skill metadata persistence |
18+
| `persistence.namespace` | `str` | No | | Key prefix for KVStore backends |
19+
| `persistence.backend` | `str` | No | | Name of backend from storage.backends |
20+
21+
## Sample Configuration
22+
23+
```yaml
24+
persistence:
25+
namespace: skills
26+
backend: kv_default
27+
```

0 commit comments

Comments
 (0)