The Skills API allows you to create, version, and manage reusable code packages that can be used across containers and responses.
Create Skill
Upload skill files as a zip archive or directory:
require "pathname"
skill = client.skills.create(
files: Pathname("my_skill.zip")
)
puts skill.id
# => "skill_abc123"
puts skill.default_version
# => "1"
Either:
- A single zip file containing the skill code
- An array of files (directory upload)
Accepts Pathname, StringIO, IO, or file content. Create from Directory
Upload multiple files as a skill:
files = [
Pathname("skill/main.py"),
Pathname("skill/helpers.py"),
Pathname("skill/config.json")
]
skill = client.skills.create(files: files)
Retrieve Skill
Get skill details:
skill = client.skills.retrieve("skill_abc123")
puts skill.name
puts skill.default_version
puts skill.created_at
The version number that will be used by default.
Unix timestamp of creation.
Unix timestamp of last update.
Update Skill
Change the default version:
updated = client.skills.update(
"skill_abc123",
default_version: "2"
)
puts updated.default_version
# => "2"
The ID of the skill to update.
The version number to set as default.
List Skills
Retrieve all skills for your project:
skills = client.skills.list(
limit: 20,
order: "desc"
)
skills.auto_paging_each do |skill|
puts "#{skill.id} (v#{skill.default_version})"
end
Number of skills to retrieve (default: 20, max: 100).
Sort order by creation time: asc or desc (default).
Delete Skill
Permanently delete a skill and all its versions:
result = client.skills.delete("skill_abc123")
puts result.deleted
# => true
Skill Versions
Create New Version
Upload a new version of an existing skill:
version = client.skills.versions.create(
"skill_abc123",
files: Pathname("my_skill_v2.zip")
)
puts version.version
# => "2"
List Versions
Get all versions of a skill:
versions = client.skills.versions.list("skill_abc123")
versions.each do |version|
puts "Version #{version.version} - #{version.created_at}"
end
Retrieve Version
Get a specific version:
version = client.skills.versions.retrieve(
"skill_abc123",
"2"
)
Delete Version
Delete a specific version:
client.skills.versions.delete("skill_abc123", "1")
Skill Content
Retrieve Skill Content
Download skill files:
content = client.skills.content.retrieve("skill_abc123")
# Save to file
File.open("skill_download.zip", "wb") do |file|
file.write(content.read)
end
Retrieve Version Content
Download a specific version:
content = client.skills.versions.content.retrieve(
"skill_abc123",
"2"
)
Using Skills
In Containers
Reference skills when creating containers:
container = client.containers.create(
name: "with-skill",
skills: [
{ skill_id: "skill_abc123" }
]
)
In Responses
Use skills in the Responses API:
response = client.responses.create(
model: "gpt-4",
input: "Use the data processing skill",
tools: [{
type: "code_interpreter",
skills: [
{ skill_id: "skill_abc123" }
]
}]
)
Inline Skills
Define skills inline without creating them first:
response = client.responses.create(
model: "gpt-4",
input: "Process data",
tools: [{
type: "code_interpreter",
skills: [{
type: "inline",
source: {
files: [{
path: "helper.py",
content: "def transform(x): return x * 2"
}]
}
}]
}]
)
Skill Structure
A skill package should follow this structure:
my_skill/
├── main.py # Entry point
├── helpers.py # Supporting modules
├── requirements.txt # Python dependencies (optional)
└── config.json # Skill configuration (optional)
Example Skill
"""Data processing skill"""
def process_data(data):
"""Main processing function"""
# Process the data
result = []
for item in data:
result.append(transform(item))
return result
def transform(item):
"""Transform a single item"""
return {
'id': item.get('id'),
'value': item.get('value', 0) * 2,
'processed': True
}
# Export functions
__all__ = ['process_data', 'transform']
Complete Example
require "openai"
require "pathname"
require "zip"
client = OpenAI::Client.new
# Create a skill from files
skill = client.skills.create(
files: Pathname("data_processor.zip")
)
puts "Skill created: #{skill.id}"
# Use in a container
container = client.containers.create(
name: "processor",
skills: [{ skill_id: skill.id }]
)
# Use in responses
response = client.responses.create(
model: "gpt-4",
input: "Process the dataset using the skill",
tools: [{
type: "code_interpreter",
container: { container_id: container.id },
skills: [{ skill_id: skill.id }]
}]
)
puts response.output.first.content
# Create new version
version2 = client.skills.versions.create(
skill.id,
files: Pathname("data_processor_v2.zip")
)
# Update default version
client.skills.update(skill.id, default_version: version2.version)
# List all versions
versions = client.skills.versions.list(skill.id)
puts "Total versions: #{versions.size}"
Best Practices
- Use semantic versioning for skill versions
- Test new versions before updating the default
- Keep previous versions available for rollback
- Document breaking changes between versions
Include a requirements.txt for Python dependencies:numpy>=1.20.0
pandas>=1.3.0
requests>=2.26.0
Always include error handling in skill functions:def process_data(data):
try:
return transform(data)
except Exception as e:
return {"error": str(e), "data": None}
- Maximum skill size: 100 MB (compressed)
- Maximum 1,000 files per skill
- Use
.gitignore patterns to exclude unnecessary files
Containers
Create execution environments
Responses API
Use skills in responses
Files API
Upload skill packages
Code Examples
Skill usage examples