Skills
Skills are knowledge packages that enable agents to execute code and generate files in isolated sandbox environments. Unlike external tools (which you implement in your backend), skills are self-contained packages with documentation and scripts that run in secure sandboxes.
Overview
Octavus Skills provide provider-agnostic code execution. They work with any LLM provider (Anthropic, OpenAI, Google) by using explicit tool calls and system prompt injection.
How Skills Work
- Skill Definition: Skills are defined in the protocol's
skills:section - Skill Resolution: Skills are resolved from available sources (see below)
- Sandbox Execution: When a skill is used, code runs in an isolated sandbox environment
- File Generation: Files saved to
/output/are automatically captured and made available for download
Skill Sources
Skills come from two sources, visible in the Skills tab of your organization:
| Source | Badge in UI | Visibility | Example |
|---|---|---|---|
| Octavus | Octavus | Available to all organizations | qr-code |
| Custom | None | Private to your organization | my-company-skill |
When you reference a skill in your protocol, Octavus resolves it from your available skills. If you create a custom skill with the same name as an Octavus skill, your custom skill takes precedence.
Defining Skills
Define skills in the protocol's skills: section:
Skill Fields
| Field | Required | Description |
|---|---|---|
display | No | How to show in UI: hidden, name, description, stream (default: description) |
description | No | Custom description shown to users (overrides skill's built-in description) |
Display Modes
| Mode | Behavior |
|---|---|
hidden | Skill usage not shown to users |
name | Shows skill name while executing |
description | Shows description while executing (default) |
stream | Streams progress if available |
Enabling Skills
After defining skills in the skills: section, specify which skills are available for the chat thread in agent.skills:
Skill Tools
When skills are enabled, the LLM has access to these tools:
| Tool | Purpose |
|---|---|
octavus_skill_read | Read skill documentation (SKILL.md) |
octavus_skill_list | List available scripts in a skill |
octavus_skill_run | Execute a pre-built script from a skill |
octavus_code_run | Execute arbitrary Python/Bash code |
octavus_file_write | Create files in the sandbox |
octavus_file_read | Read files from the sandbox |
The LLM learns about available skills through system prompt injection and can use these tools to interact with skills.
Example: QR Code Generation
When a user asks "Create a QR code for octavus.ai", the LLM will:
- Recognize the task matches the
qr-codeskill - Call
octavus_skill_readto learn how to use the skill - Execute code (via
octavus_code_runoroctavus_skill_run) to generate the QR code - Save the image to
/output/in the sandbox - The file is automatically captured and made available for download
File Output
Files saved to /output/ in the sandbox are automatically:
- Captured after code execution
- Uploaded to S3 storage
- Made available via presigned URLs
- Included in the message as file parts
Files persist across page refreshes and are stored in the session's message history.
Skill Format
Skills follow the Agent Skills open standard:
SKILL.md- Required skill documentation with YAML frontmatterscripts/- Optional executable code (Python/Bash)references/- Optional documentation loaded as neededassets/- Optional files used in outputs (templates, images)
SKILL.md Format
Scripts Reference
scripts/generate.py
Main script for generating QR codes...
2. When to Use Skills vs Tools
| Use Skills When | Use Tools When |
|---|---|
| Code execution needed | Simple API calls |
| File generation | Database queries |
| Complex calculations | External service integration |
| Data processing | Authentication required |
| Provider-agnostic needed | Backend-specific logic |
3. Skill Selection
Define all skills available to this agent in the skills: section. Then specify which skills are available for the chat thread in agent.skills:
4. Display Modes
Choose appropriate display modes based on user experience:
Comparison: Skills vs Tools vs Provider Options
| Feature | Octavus Skills | External Tools | Provider Tools/Skills |
|---|---|---|---|
| Execution | Isolated sandbox | Your backend | Provider servers |
| Provider | Any (agnostic) | N/A | Provider-specific |
| Code Execution | Yes | No | Yes (provider tools) |
| File Output | Yes | No | Yes (provider skills) |
| Implementation | Skill packages | Your code | Built-in |
| Cost | Sandbox + LLM API | Your infrastructure | Included in API |
Uploading Custom Skills
You can upload custom skills to your organization:
- Create a skill following the Agent Skills format
- Package it as a
.skillbundle (ZIP file) - Upload via the platform UI
- Reference by slug in your protocol
Security
Skills run in isolated sandbox environments:
- No network access (unless explicitly configured)
- No persistent storage (sandbox destroyed after execution)
- File output only via
/output/directory - Time limits enforced (5-minute default timeout)
Next Steps
- Agent Config — Configuring skills in agent settings
- Provider Options — Anthropic's built-in skills
- Skills Advanced Guide — Best practices and advanced patterns