feat(OpenAI): add Skills API

README.md

@@ -34,6 +34,8 @@ If you or your business relies on this package, it's important to support the de
   - [Conversations Items Resource](#conversations-items-resource)
   - [Containers Resource](#containers-resource)
   - [Containers Files Resource](#containers-files-resource)
+  - [Skills Resource](#skills-resource)
+  - [Skills Versions Resource](#skills-versions-resource)
   - [Chat Resource](#chat-resource)
   - [Audio Resource](#audio-resource)
   - [Embeddings Resource](#embeddings-resource)
@@ -690,6 +692,167 @@ $response->deleted; // true
 $response->toArray(); // ['id' => 'cfile_...', 'object' => 'container.file.deleted', 'deleted' => true]
 ```
 
+### `Skills` Resource
+
+Skills give an agent reusable instructions and supporting files. Upload a skill either as a zip bundle or as a directory of files, then reference it from the Responses API shell tool via `skill_reference`.
+
+#### `create`
+
+Creates a skill from a zip bundle, or from several files that share a single top-level folder.
+
+```php
+// Zip upload
+$response = $client->skills()->create([
+    'files' => fopen('basic_math.zip', 'r'),
+]);
+
+// Directory upload
+$response = $client->skills()->create([
+    'files' => [
+        fopen('basic_math/SKILL.md', 'r'),
+        fopen('basic_math/calculate.py', 'r'),
+    ],
+]);
+
+$response->id; // 'skill_abc123'
+$response->name; // 'basic-math'
+$response->defaultVersion; // '1'
+$response->latestVersion; // '1'
+
+$response->toArray(); // ['id' => 'skill_abc123', ...]
+```
+
+#### `list`
+
+Lists the skills in the current project.
+
+```php
+$response = $client->skills()->list([
+    'limit' => 10,
+]);
+
+$response->object; // 'list'
+$response->hasMore; // false
+
+foreach ($response->data as $result) {
+    $result->id; // 'skill_abc123'
+    $result->name; // 'basic-math'
+}
+
+$response->toArray(); // ['object' => 'list', 'data' => [...], ...]
+```
+
+#### `retrieve`
+
+Retrieves a skill by its ID.
+
+```php
+$response = $client->skills()->retrieve('skill_abc123');
+
+$response->id; // 'skill_abc123'
+$response->description; // 'Add or multiply numbers.'
+
+$response->toArray(); // ['id' => 'skill_abc123', ...]
+```
+
+#### `update`
+
+Updates the default version pointer for a skill.
+
+```php
+$response = $client->skills()->update('skill_abc123', [
+    'default_version' => '2',
+]);
+
+$response->defaultVersion; // '2'
+```
+
+#### `content`
+
+Downloads the zip bundle for a skill's default version.
+
+```php
+$zip = $client->skills()->content('skill_abc123');
+
+file_put_contents('basic_math.zip', $zip);
+```
+
+#### `delete`
+
+Deletes a skill and all of its versions.
+
+```php
+$response = $client->skills()->delete('skill_abc123');
+
+$response->id; // 'skill_abc123'
+$response->object; // 'skill.deleted'
+$response->deleted; // true
+
+$response->toArray(); // ['id' => 'skill_abc123', ...]
+```
+
+### `Skills Versions` Resource
+
+#### `create`
+
+Creates a new immutable version of a skill. Pass `default` to make it the default version.
+
+```php
+$response = $client->skills()->versions()->create('skill_abc123', [
+    'files' => fopen('basic_math_v2.zip', 'r'),
+    'default' => 'true',
+]);
+
+$response->id; // 'skillver_abc123'
+$response->version; // '2'
+
+$response->toArray(); // ['id' => 'skillver_abc123', ...]
+```
+
+#### `list`
+
+Lists the versions of a skill.
+
+```php
+$response = $client->skills()->versions()->list('skill_abc123', [
+    'order' => 'desc',
+]);
+
+foreach ($response->data as $result) {
+    $result->version; // '2'
+}
+```
+
+#### `retrieve`
+
+Retrieves a specific version of a skill.
+
+```php
+$response = $client->skills()->versions()->retrieve('skill_abc123', '2');
+
+$response->skillId; // 'skill_abc123'
+$response->version; // '2'
+```
+
+#### `content`
+
+Downloads the zip bundle for a specific skill version.
+
+```php
+$zip = $client->skills()->versions()->content('skill_abc123', '2');
+```
+
+#### `delete`
+
+Deletes a skill version. The default version cannot be deleted; set another default first.
+
+```php
+$response = $client->skills()->versions()->delete('skill_abc123', '1');
+
+$response->object; // 'skill.version.deleted'
+$response->deleted; // true
+```
+
 ### `Chat` Resource
 
 #### `create`

src/Client.php

@@ -26,6 +26,7 @@
 use OpenAI\Resources\Moderations;
 use OpenAI\Resources\Realtime;
 use OpenAI\Resources\Responses;
+use OpenAI\Resources\Skills;
 use OpenAI\Resources\Threads;
 use OpenAI\Resources\VectorStores;
 
@@ -90,6 +91,16 @@ public function containers(): Containers
         return new Containers($this->transporter);
     }
 
+    /**
+     * Create and manage skills for use with the Responses API shell tools.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills
+     */
+    public function skills(): Skills
+    {
+        return new Skills($this->transporter);
+    }
+
     /**
      * Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms.
      *

src/Contracts/ClientContract.php

@@ -19,6 +19,7 @@
 use OpenAI\Contracts\Resources\ModerationsContract;
 use OpenAI\Contracts\Resources\RealtimeContract;
 use OpenAI\Contracts\Resources\ResponsesContract;
+use OpenAI\Contracts\Resources\SkillsContract;
 use OpenAI\Contracts\Resources\ThreadsContract;
 use OpenAI\Contracts\Resources\VectorStoresContract;
 
@@ -67,6 +68,13 @@ public function chat(): ChatContract;
      */
     public function containers(): ContainersContract;
 
+    /**
+     * Create and manage skills for use with the Responses API shell tools.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills
+     */
+    public function skills(): SkillsContract;
+
     /**
      * Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms.
      *

src/Contracts/Resources/SkillVersionsContract.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Skills\Versions\SkillVersionDeleteResponse;
+use OpenAI\Responses\Skills\Versions\SkillVersionListResponse;
+use OpenAI\Responses\Skills\Versions\SkillVersionResponse;
+
+interface SkillVersionsContract
+{
+    /**
+     * Create a new immutable skill version.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills/subresources/versions/methods/create
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(string $skillId, array $parameters): SkillVersionResponse;
+
+    /**
+     * List skill versions for a skill.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills/subresources/versions/methods/list
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function list(string $skillId, array $parameters = []): SkillVersionListResponse;
+
+    /**
+     * Get a specific skill version.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills/subresources/versions/methods/retrieve
+     */
+    public function retrieve(string $skillId, string $version): SkillVersionResponse;
+
+    /**
+     * Download a skill version zip bundle.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills/subresources/versions/subresources/content/methods/retrieve
+     */
+    public function content(string $skillId, string $version): string;
+
+    /**
+     * Delete a skill version.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills/subresources/versions/methods/delete
+     */
+    public function delete(string $skillId, string $version): SkillVersionDeleteResponse;
+}

src/Contracts/Resources/SkillsContract.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Skills\SkillDeleteResponse;
+use OpenAI\Responses\Skills\SkillListResponse;
+use OpenAI\Responses\Skills\SkillResponse;
+
+interface SkillsContract
+{
+    /**
+     * Create a new skill by uploading its files (directory upload) or a single zip bundle.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills/methods/create
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(array $parameters): SkillResponse;
+
+    /**
+     * List all skills for the current project.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills/methods/list
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function list(array $parameters = []): SkillListResponse;
+
+    /**
+     * Get a skill by its ID.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills/methods/retrieve
+     */
+    public function retrieve(string $id): SkillResponse;
+
+    /**
+     * Update the default version pointer for a skill.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills/methods/update
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function update(string $id, array $parameters): SkillResponse;
+
+    /**
+     * Download a skill zip bundle by its ID.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills/subresources/content/methods/retrieve
+     */
+    public function content(string $id): string;
+
+    /**
+     * Delete a skill by its ID.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills/methods/delete
+     */
+    public function delete(string $id): SkillDeleteResponse;
+
+    /**
+     * Manage the immutable versions of a skill.
+     *
+     * @see https://developers.openai.com/api/reference/resources/skills/subresources/versions
+     */
+    public function versions(): SkillVersionsContract;
+}