Skills

Skills are knowledge packages that enable agents to execute code and generate files. Unlike external tools (which you implement in your backend), skills are self-contained packages with documentation and scripts. By default, skills run in isolated sandbox environments, but they can also run directly on the agent's computer.

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

1. Skill Definition: Skills are defined in the protocol's skills: section
2. Skill Resolution: Skills are resolved from available sources (see below)
3. Execution: Code runs in an isolated sandbox (default) or on the agent's computer
4. File Generation: Files saved to /output/ are automatically captured and made available for download (sandbox skills)

Skill Sources

Skills come from two sources, visible in the Skills tab of your organization:

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

Display Modes

The display setting on a skill applies to all tools under that skill namespace. See Tool Display Modes for full details on each mode.

Enabling Skills

After defining skills in the skills: section, specify which skills are available. Skills work in both interactive agents and workers.

Interactive Agents

Reference skills in agent.skills:

Workers and Named Threads

Reference skills per-thread in start-thread.skills:

This also works for named threads in interactive agents, allowing different threads to have different skills.

Skill Tools

When skills are enabled, the LLM has access to these tools:

The LLM learns about available skills through system prompt injection and can use these tools to interact with skills.

Skills that have secrets configured run in secure mode, where only octavus_skill_read, octavus_skill_list, and octavus_skill_run are available. See Skill Secrets below.

Device Execution

By default, skills run in an isolated sandbox. When execution: device is set, the skill runs on the agent's computer (VM or desktop) instead.

How Device Skills Work

Device skills are installed on the agent's computer so the agent can browse their files and run their scripts directly. After attaching a skill via integrations, the agent uses octavus_skill_setup to install it on the device. Once installed, the agent can:

• Read the skill's documentation with octavus_skill_read
• List available scripts with octavus_skill_list
• Run pre-built scripts with octavus_skill_run

The generic workspace tools (octavus_code_run, octavus_file_write, octavus_file_read) are not available for device skills. Instead, the agent uses the device's own shell and filesystem MCP servers to interact with files and run commands.

Sandbox vs Device Skills

When to Use Device Execution

Use execution: device when the skill needs to:

• Access the agent's local filesystem or running processes
• Use tools or CLIs installed on the device
• Interact with services running on the device
• Persist files beyond a single execution cycle

Example: QR Code Generation

When a user asks "Create a QR code for octavus.ai", the LLM will:

1. Recognize the task matches the qr-code skill
2. Call octavus_skill_read to learn how to use the skill
3. Execute code (via octavus_code_run or octavus_skill_run) to generate the QR code
4. Save the image to /output/ in the sandbox
5. The file is automatically captured and made available for download

File Output

Files saved to /output/ in the sandbox are automatically:

1. Captured after code execution
2. Uploaded to S3 storage
3. Made available via presigned URLs
4. 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 frontmatter
• scripts/ - Optional executable code (Python/Bash)
• references/ - Optional documentation loaded as needed
• assets/ - 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

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

Uploading Custom Skills

You can upload custom skills to your organization using the CLI or the platform UI.

Via CLI (Recommended)

Use octavus skills sync to package and upload a skill directory. If the skill has a .env file, secrets are pushed alongside the bundle:

Skill Directory Structure

Once uploaded, reference the skill by slug in your protocol:

On-Demand Skills

On-demand skills (onDemandSkills) also support the execution field:

When execution: device is set on the on-demand skills declaration, any skill attached at runtime via integrations runs on the agent's computer instead of in a sandbox.

Sandbox Timeout

The default sandbox timeout is 5 minutes (applies to sandbox skills only). You can configure a custom timeout using sandboxTimeout in the agent config or on individual start-thread blocks:

Thread-level sandboxTimeout takes priority over agent-level. Maximum: 1 hour (3,600,000 ms).

Skill Secrets

Skills can declare secrets they need to function. When an organization configures those secrets, the skill runs in secure mode with additional isolation.

Declaring Secrets

Add a secrets array to your SKILL.md frontmatter:

Each secret declaration has:

Secret names must match the pattern ^[A-Z_][A-Z0-9_]*$ (uppercase letters, digits, and underscores).

Configuring Secrets

Organization admins configure secret values through the skill editor in the platform UI. Each organization maintains its own independent set of secrets for each skill.

Secrets are encrypted at rest and only decrypted at execution time.

Secure Mode

When a skill has secrets configured for the organization, it automatically runs in secure mode:

• The skill gets its own isolated sandbox (separate from other skills)
• Secrets are injected as environment variables available to all scripts
• Only octavus_skill_read, octavus_skill_list, and octavus_skill_run are available - octavus_code_run, octavus_file_write, and octavus_file_read are blocked
• Scripts receive input as JSON via stdin (using the input parameter on octavus_skill_run) instead of CLI args
• All output (stdout/stderr) is automatically redacted for secret values before being returned to the LLM

Writing Scripts for Secure Skills

Scripts in secure skills read input from stdin as JSON and access secrets from environment variables:

For standard skills (without secrets), scripts receive input as CLI arguments. For secure skills, always use stdin JSON.

Security

Sandbox skills run in isolated environments:

• No network access (unless explicitly configured)
• No persistent storage (sandbox destroyed after each next-message execution)
• File output only via /output/ directory
• Time limits enforced (5-minute default, configurable via sandboxTimeout)
• Secret redaction - output from secure skills is automatically scanned for secret values

Device skills run on the agent's computer and share its environment. They do not have sandbox isolation but benefit from restricted tool access (only slug-bearing tools are available).

Next Steps

• Agent Config - Configuring skills in agent settings
• Provider Options - Anthropic's built-in skills
• Skills Advanced Guide - Best practices and advanced patterns