Skills
Skills are reusable packages of instructions and files that give assistants specialized capabilities. A skill might contain a data analysis script, a content template, a code library, or any other resource an assistant can use during conversations.
How Skills Work
Each skill is defined by a SKILL.md file containing:
- YAML frontmatter with metadata (name, description, license, compatibility)
- Markdown body with detailed instructions for the assistant
Skills can also include additional files — scripts, templates, data files, or any other resources the assistant might need.
When a skill is enabled on an assistant, its description is included in the assistant’s context. The assistant can then use the activate_skill tool to load the full skill instructions and read_skill_resource to access skill files during a conversation.
Technical Details
Three-tier progressive disclosure — Skills use a progressive disclosure model to minimize context size and keep the system prompt concise:
- Tier 1 — Catalog. Only the skill’s name and one-line description are included in the system prompt. This lets the LLM know what skills are available without consuming context with full instructions.
- Tier 2 — Activation. When the LLM calls
activate_skill, the full SKILL.md instructions are loaded and returned as the tool result. The LLM now has the complete instructions and a listing of available resource files. - Tier 3 — Resources. Individual files (scripts, templates, data) are loaded on demand via
read_skill_resource. This avoids loading large files unless the assistant actually needs them.
Persistence across turns — When a skill is activated, its ID is saved to the conversation record. On subsequent turns, previously activated skills are automatically restored into the agent’s context without requiring re-activation. This means the assistant retains skill knowledge across a multi-turn conversation.
Sandbox integration — When a skill contains executable scripts and the assistant uses execute_code, the skill’s script files are automatically copied into the sandbox container on first use. This happens transparently — the assistant can reference skill scripts by their relative paths in code execution without any extra setup.
Creating a Skill
Navigate to Skills in the sidebar and click New Skill.
| Field | Description |
|---|---|
| Name | A kebab-case identifier (lowercase letters, numbers, and hyphens only). E.g., data-analysis, blog-writer |
| Description | A brief description of what the skill does (max 1024 characters) |
| License | Optional license identifier (e.g., MIT, Apache-2.0) |
| Compatibility | Optional compatibility notes (e.g., “Requires Python 3.10+”) |
| Instructions | The main skill instructions in Markdown. This is the body of the SKILL.md file. |
Uploading a Skill
You can also upload a skill as a ZIP file. The ZIP should contain a SKILL.md file at the root with valid YAML frontmatter (at minimum, name and description fields). Any other files in the ZIP are imported as skill files.
Hidden files (starting with .) and macOS metadata folders (__MACOSX/) are automatically filtered out during import.
Managing Skill Files
On the skill detail page, you can manage the skill’s files:
- Add File — Create a new file with a relative path (e.g.,
scripts/run.py,templates/report.html) - Edit File — Modify the content of text-based files
- Delete File — Remove individual files or bulk-delete multiple files
- Download — Export the entire skill as a ZIP file
Files are grouped by directory in the detail view for easy navigation.
Binary Files
Skills support binary files like images, fonts, PDFs, and archives. These are stored as-is and can be read by the assistant using the read_skill_resource tool. Supported binary formats include PNG, JPG, SVG, PDF, ZIP, MP3, MP4, and font files.
Assigning Skills to Assistants
Skills are assigned to assistants on the assistant detail page under the Skills tab. Toggle a skill on or off for each assistant independently.
When a skill is enabled:
- The skill’s description appears in the assistant’s available skills context
- The assistant can activate the skill to load its full instructions
- The assistant can read skill files for scripts, templates, or other resources
- Activated skills persist across conversation turns for ongoing access
Downloading and Sharing
Click Download on the skill detail page to export it as a ZIP file. This ZIP can be shared with others and imported using the Upload feature. The ZIP includes the SKILL.md file and all associated files.