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

1. Skill Definition: Skills are defined in the protocol's skills: section
2. Skill Resolution: Skills are resolved from available sources (see below)
3. Sandbox Execution: When a skill is used, code runs in an isolated sandbox environment
4. 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:

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

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.

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:

Sandbox Timeout

The default sandbox timeout is 5 minutes. 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

Skills run in isolated sandbox 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

Next Steps

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