Skills

Purpose and Scope

Skills are reusable, versioned bundles of files that an agent workflow can mount or reference as a capability. In the product documentation, a skill is described as a directory or zip bundle containing a manifest named SKILL.md, with front matter and instructions that explain when and how the bundle should be used. In this SDK, the Skills surface gives TypeScript and JavaScript applications a generated resource for creating those bundles, listing the skills available to the current project, retrieving metadata, updating the default version pointer, deleting a skill, and downloading the uploaded content bundle.

The main developer problem this page solves is mapping the agent concept of a reusable skill to the concrete SDK calls exposed by client.skills. The resource model is intentionally small: a skill has stable metadata, a latest version, and a default version, while nested resources cover downloadable content and version-specific operations. That separation matters when an application wants to upload improved files without changing every workflow immediately. The default version can be moved deliberately, while callers that need exact reproducibility can work with the version namespace rather than treating the skill as a mutable blob.

Sources: src/resources/skills/skills.ts, src/resources/skills/content.ts, src/resources/skills/index.ts, src/resources/skills/versions/index.ts

Relevant Source Files

• src/resources/skills.ts - Top-level re-export that makes the generated Skills resource family available through the package resource tree.
• src/resources/skills/index.ts - Barrel file exporting Content, Skills, version resources, page types, model types, and request parameter types for the Skills namespace.
• src/resources/skills/skills.ts - Implements the primary Skills API resource, including create, retrieve, update, list, and delete methods plus core Skill and request interfaces.
• src/resources/skills/content.ts - Implements binary download of a skill zip bundle using the /skills/{skillID}/content endpoint and binary response handling.
• src/resources/skills/versions/index.ts - Exports the nested version resource, version model types, request parameter types, pagination type, and version content retrieval type.
• src/resources/admin/organization/projects/hosted-tool-permissions.ts - Shows the adjacent admin surface for enabling or disabling hosted tools such as code interpreter, file search, image generation, MCP, and web search at the project level.

System-to-Code Mapping

At the SDK level, Skills extends the common generated APIResource base and attaches two nested resource objects: content and versions. That shape is the main signal for how to navigate the API. Use the root resource when the operation is about the skill as a named capability, use content when the operation is about downloading the stored file bundle, and use versions when the operation is about a particular uploaded version. The top-level src/resources/skills.ts file re-exports the namespace, while the local index files publish the concrete classes and TypeScript types that application code can import.

Sources: src/resources/skills.ts, src/resources/skills/index.ts, src/resources/skills/skills.ts, src/resources/skills/content.ts, src/resources/skills/versions/index.ts

The generated Skill interface exposes the metadata that most applications need for selection and display. It includes a unique identifier, creation timestamp, name, description, object discriminator, latest version, and default version. The distinction between latest and default is important for workflow stability. A newly uploaded version may be visible as the latest version before an operator decides to promote it. The update method focuses specifically on changing the default version pointer, which lets teams roll forward or roll back the version their agent workflows should use by default.

The create path accepts SkillCreateParams, where files can be either an array of uploadable values or a single uploadable value. The implementation wraps the request with multipart form handling, matching the documented upload model where callers can send either multiple files representing a directory tree or a zip archive. Because the SDK type is expressed as Uploadable, the same high-level resource can support file handles, blobs, or other uploadable objects supported by the SDK runtime. The method returns an APIPromise<Skill>, so successful creation gives callers the server-side identifier and version metadata needed for later workflow configuration.

Execution Flow

A typical skill lifecycle starts outside the SDK with a directory that contains the skill manifest and any supporting scripts, documents, templates, or data files. After preparing that bundle, the application calls client.skills.create with multipart upload data. The returned skill record should be stored wherever the application keeps agent configuration, because the ID is the stable handle for future retrieval and content download. When a user or deployment process needs to inspect available capabilities, client.skills.list returns a cursor-paginated page of Skill objects for the current project.

After creation, applications can retrieve a single skill by ID to refresh metadata, or delete it when the capability should no longer be available. Updating a skill does not upload files in the root update method; it changes the default version to a supplied version number. That means version creation and deletion belong to the nested versions namespace, while the root update operation is a pointer-management operation. This model is useful in production because workflows can keep using the current default until validation, review, or evaluation has confirmed that a newer version should become active.

Sources: src/resources/skills/skills.ts, src/resources/skills/versions/index.ts

Downloading content is handled separately through client.skills.content.retrieve. That method returns a binary Response, sets an Accept header for binary content, and marks the operation as a binary response internally. In practice, use it when an administration UI, deployment tool, or audit process needs to fetch the zip bundle that represents the uploaded skill. Because the method targets the skill ID rather than a local file path, callers should treat the result as server-held bundle content and then decide whether to stream it to disk, inspect it, or pass it through another storage layer.

API Components

Component	SDK surface	Behavior
Skill creation	client.skills.create(body, options?)	Uploads skill files or a zip bundle with bearer authentication and multipart request handling.
Skill retrieval	client.skills.retrieve(skillID, options?)	Gets metadata for one skill ID.
Default version update	client.skills.update(skillID, body, options?)	Sets default_version for the skill.
Skill listing	client.skills.list(query?, options?)	Returns a cursor-paginated list of skills for the current project.
Skill deletion	client.skills.delete(skillID, options?)	Deletes a skill and returns DeletedSkill.
Content download	client.skills.content.retrieve(skillID, options?)	Downloads the skill zip bundle as a binary response.
Version namespace	client.skills.versions	Exposes generated version operations and version types through the Skills namespace.

The compact reference above reflects the public contracts visible in the generated resource files. DeletedSkill contains id, deleted, and the object discriminator skill.deleted. SkillListParams extends the shared cursor pagination parameters and includes ordering by timestamp. SkillUpdateParams requires default_version, which makes promotion explicit rather than accidental. The version index exports SkillVersion, SkillVersionList, DeletedSkillVersion, VersionCreateParams, VersionRetrieveParams, VersionListParams, VersionDeleteParams, and SkillVersionsPage, so TypeScript callers can type version workflows even when they import from the namespace barrel instead of the deeper implementation path.

Sources: src/resources/skills/index.ts, src/resources/skills/versions/index.ts, src/resources/skills/skills.ts

Relationship to Agent and Hosted Tool Workflows

Skills fit naturally beside agent instructions and tools. Product documentation frames an agent as a package of model choice, instructions, tools, guardrails, and optional runtime behavior. A skill is narrower: it is a reusable bundle of files and instructions that can encode a process or convention, such as a company writing style, a data transformation script, or a multi-step operations runbook. Use ordinary agent instructions for stable behavioral guidance, and use skills when the reusable capability needs files, versioning, and independent lifecycle management.

The repository also includes an admin resource for hosted tool permissions at the project level. That resource retrieves and updates enablement states for hosted tools including code interpreter, file search, image generation, MCP, and web search. Skills are not modeled in that permission object in the supplied source, but the file is still relevant context for administrators planning hosted agent deployments. It shows that tool availability can be governed separately from uploading reusable skill bundles. In other words, a project may need both the right uploaded skill content and the right hosted tool permissions for a complete production workflow.

Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts, src/resources/skills/skills.ts

Practical Usage Notes

When designing an application around skills, keep the skill ID, default version, and latest version visible to operators. The ID is the durable reference, while the version fields explain what content is available and what content should be used by default. For safe rollout, create or manage versions first, validate the new bundle in a test workflow, and only then call the update operation to move the default pointer. If a UI lets users download bundles, use the content resource and handle the result as binary data rather than expecting JSON metadata.

Next, read the pages on agent definitions, tools and approvals, Code Interpreter, MCP integrations, and deployment data controls. Those topics explain how reusable capabilities are attached to model workflows, how hosted tools are enabled or governed, and how production applications should think about permissions, runtime environments, and auditability. For lower-level SDK mechanics, pair this page with the client and resource model reference so the generated APIResource, pagination, request options, upload handling, and promise-returning methods are familiar before building a complete skills administration flow.