@octavus/docs 0.0.9 → 1.0.0

package/content/04-protocol/{07-provider-options.md → 08-provider-options.md}

@@ -7,6 +7,8 @@ description: Configuring provider-specific tools and features.
 
 Provider options let you enable provider-specific features like Anthropic's built-in tools and skills. These features run server-side on the provider's infrastructure.
 
+> **Note**: For provider-agnostic code execution, use [Octavus Skills](/docs/protocol/skills) instead. Octavus Skills work with any LLM provider and run in isolated sandbox environments.
+
 ## Anthropic Options
 
 Configure Anthropic-specific features when using `anthropic/*` models:
@@ -41,9 +43,9 @@ Provider tools are executed server-side by the provider (Anthropic). Unlike exte
 
 ### Available Tools
 
-| Tool | Description |
-|------|-------------|
-| `web-search` | Search the web for current information |
+| Tool             | Description                                  |
+| ---------------- | -------------------------------------------- |
+| `web-search`     | Search the web for current information       |
 | `code-execution` | Execute Python/Bash in a sandboxed container |
 
 ### Tool Configuration
@@ -52,14 +54,14 @@ Provider tools are executed server-side by the provider (Anthropic). Unlike exte
 anthropic:
   tools:
     web-search:
-      display: description      # How to show in UI
+      display: description # How to show in UI
       description: Searching... # Custom display text
 ```
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `display` | No | `hidden`, `name`, `description`, or `stream` (default: `description`) |
-| `description` | No | Custom text shown to users during execution |
+| Field         | Required | Description                                                           |
+| ------------- | -------- | --------------------------------------------------------------------- |
+| `display`     | No       | `hidden`, `name`, `description`, or `stream` (default: `description`) |
+| `description` | No       | Custom text shown to users during execution                           |
 
 ### Web Search
 
@@ -76,6 +78,7 @@ agent:
 ```
 
 Use cases:
+
 - Current events and news
 - Real-time data (prices, weather)
 - Fact verification
@@ -96,6 +99,7 @@ agent:
 ```
 
 Use cases:
+
 - Data analysis and calculations
 - File processing
 - Chart generation
@@ -105,7 +109,9 @@ Use cases:
 
 ## Skills
 
-Skills are knowledge packages that give the agent specialized capabilities. They're loaded into the code execution container at `/skills/{skill-id}/`.
+> **Important**: This section covers **Anthropic's built-in skills** (provider-specific). For provider-agnostic skills that work with any LLM, see [Octavus Skills](/docs/protocol/skills).
+
+Anthropic skills are knowledge packages that give the agent specialized capabilities. They're loaded into Anthropic's code execution container at `/skills/{skill-id}/` and only work with Anthropic models.
 
 ### Skill Configuration
 
@@ -113,29 +119,29 @@ Skills are knowledge packages that give the agent specialized capabilities. They
 anthropic:
   skills:
     pdf:
-      type: anthropic          # 'anthropic' or 'custom'
-      version: latest          # Optional version
+      type: anthropic # 'anthropic' or 'custom'
+      version: latest # Optional version
       display: description
       description: Processing PDF
 ```
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `type` | Yes | `anthropic` (built-in) or `custom` (uploaded) |
-| `version` | No | Skill version (default: `latest`) |
-| `display` | No | `hidden`, `name`, `description`, or `stream` (default: `description`) |
-| `description` | No | Custom text shown to users |
+| Field         | Required | Description                                                           |
+| ------------- | -------- | --------------------------------------------------------------------- |
+| `type`        | Yes      | `anthropic` (built-in) or `custom` (uploaded)                         |
+| `version`     | No       | Skill version (default: `latest`)                                     |
+| `display`     | No       | `hidden`, `name`, `description`, or `stream` (default: `description`) |
+| `description` | No       | Custom text shown to users                                            |
 
 ### Built-in Skills
 
 Anthropic provides several built-in skills:
 
-| Skill ID | Purpose |
-|----------|---------|
-| `pdf` | PDF manipulation, text extraction, form filling |
-| `xlsx` | Excel spreadsheet operations and analysis |
-| `docx` | Word document creation and editing |
-| `pptx` | PowerPoint presentation creation |
+| Skill ID | Purpose                                         |
+| -------- | ----------------------------------------------- |
+| `pdf`    | PDF manipulation, text extraction, form filling |
+| `xlsx`   | Excel spreadsheet operations and analysis       |
+| `docx`   | Word document creation and editing              |
+| `pptx`   | PowerPoint presentation creation                |
 
 ### Using Skills
 
@@ -154,6 +160,7 @@ agent:
 ```
 
 When skills are configured:
+
 1. Code execution is automatically enabled
 2. Skill files are loaded into the container
 3. The agent can read skill instructions and execute scripts
@@ -165,26 +172,39 @@ You can create and upload custom skills to Anthropic:
 ```yaml
 anthropic:
   skills:
-    my-custom-skill:
+    custom-analysis:
       type: custom
       version: latest
       description: Running custom analysis
 ```
 
 Custom skills follow the [Agent Skills standard](https://agentskills.io) and contain:
+
 - `SKILL.md` with instructions and metadata
 - Optional `scripts/`, `references/`, and `assets/` directories
 
+### Octavus Skills vs Anthropic Skills
+
+| Feature           | Anthropic Skills         | Octavus Skills                |
+| ----------------- | ------------------------ | ----------------------------- |
+| **Provider**      | Anthropic only           | Any (agnostic)                |
+| **Execution**     | Anthropic's container    | Isolated sandbox              |
+| **Configuration** | `agent.anthropic.skills` | `agent.skills`                |
+| **Definition**    | `anthropic:` section     | `skills:` section             |
+| **Use Case**      | Claude-specific features | Cross-provider code execution |
+
+For provider-agnostic code execution, use Octavus Skills defined in the protocol's `skills:` section and enabled via `agent.skills`. See [Skills](/docs/protocol/skills) for details.
+
 ## Display Modes
 
 Both tools and skills support display modes:
 
-| Mode | Behavior |
-|------|----------|
-| `hidden` | Not shown to users |
-| `name` | Shows the tool/skill name |
+| Mode          | Behavior                        |
+| ------------- | ------------------------------- |
+| `hidden`      | Not shown to users              |
+| `name`        | Shows the tool/skill name       |
 | `description` | Shows the description (default) |
-| `stream` | Streams progress if available |
+| `stream`      | Streams progress if available   |
 
 ## Full Example
 
@@ -203,7 +223,7 @@ agent:
   model: anthropic/claude-sonnet-4-5
   system: system
   input: [COMPANY_NAME, USER_ID]
-  tools: [get-user-account]  # External tools
+  tools: [get-user-account] # External tools
   agentic: true
   thinking: medium
 
@@ -237,14 +257,14 @@ triggers:
 handlers:
   user-message:
     Add message:
-      type: add-message
+      block: add-message
       role: user
       prompt: user-message
       input: [USER_MESSAGE]
       display: hidden
 
     Respond:
-      type: next-message
+      block: next-message
 ```
 
 ## Validation
@@ -265,11 +285,10 @@ The protocol validator enforces:
 ```yaml
 # This will fail validation
 agent:
-  model: openai/gpt-4o  # OpenAI model
-  anthropic:            # Anthropic options - mismatch!
+  model: openai/gpt-4o # OpenAI model
+  anthropic: # Anthropic options - mismatch!
     tools:
       web-search: {}
 ```
 
 Error: `"anthropic" options require an anthropic model. Current model provider: "openai"`
-

package/content/04-protocol/09-skills-advanced.md

@@ -0,0 +1,439 @@
+---
+title: Skills Advanced Guide
+description: Best practices and advanced patterns for using Octavus skills.
+---
+
+# Skills Advanced Guide
+
+This guide covers advanced patterns and best practices for using Octavus skills in your agents.
+
+## When to Use Skills
+
+Skills are ideal for:
+
+- **Code execution** - Running Python/Bash scripts
+- **File generation** - Creating images, PDFs, reports
+- **Data processing** - Analyzing, transforming, or visualizing data
+- **Provider-agnostic needs** - Features that should work with any LLM
+
+Use external tools instead when:
+
+- **Simple API calls** - Database queries, external services
+- **Authentication required** - Accessing user-specific resources
+- **Backend integration** - Tight coupling with your infrastructure
+
+## Skill Selection Strategy
+
+### Defining Available Skills
+
+Define all skills available to this agent in the `skills:` section. Then specify which skills are available for the chat thread in `agent.skills`:
+
+```yaml
+# All skills available to this agent (defined once at protocol level)
+skills:
+  qr-code:
+    display: description
+    description: Generating QR codes
+  pdf-processor:
+    display: description
+    description: Processing PDFs
+  data-analysis:
+    display: description
+    description: Analyzing data
+
+# Skills available for this chat thread
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  skills: [qr-code] # Skills available for this thread
+```
+
+### Match Skills to Use Cases
+
+Define all skills available to this agent in the `skills:` section. Then specify which skills are available for the chat thread based on use case:
+
+```yaml
+# All skills available to this agent (defined once at protocol level)
+skills:
+  qr-code:
+    display: description
+    description: Generating QR codes
+  data-analysis:
+    display: description
+    description: Analyzing data and generating reports
+  visualization:
+    display: description
+    description: Creating charts and visualizations
+
+# Skills available for this chat thread (support use case)
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  skills: [qr-code] # Skills available for this thread
+```
+
+For a data analysis thread, you would specify `[data-analysis, visualization]` in `agent.skills`, but still define all available skills in the `skills:` section above.
+
+## Display Mode Strategy
+
+Choose display modes based on user experience:
+
+```yaml
+skills:
+  # Background processing - hide from user
+  data-analysis:
+    display: hidden
+
+  # User-facing generation - show description
+  qr-code:
+    display: description
+
+  # Interactive progress - stream updates
+  report-generation:
+    display: stream
+```
+
+### Guidelines
+
+- **`hidden`**: Background work that doesn't need user awareness
+- **`description`**: User-facing operations (default)
+- **`name`**: Quick operations where name is sufficient
+- **`stream`**: Long-running operations where progress matters
+
+## System Prompt Integration
+
+Skills are automatically injected into the system prompt. The LLM learns:
+
+1. **Available skills** - List of enabled skills with descriptions
+2. **How to use skills** - Instructions for using skill tools
+3. **Tool reference** - Available skill tools (`octavus_skill_read`, `octavus_code_run`, etc.)
+
+You don't need to manually document skills in your system prompt. However, you can guide the LLM:
+
+```markdown
+<!-- prompts/system.md -->
+
+You are a helpful assistant that can generate QR codes.
+
+## When to Generate QR Codes
+
+Generate QR codes when users want to:
+
+- Share URLs easily
+- Provide contact information
+- Share WiFi credentials
+- Create scannable data
+
+Use the qr-code skill for all QR code generation tasks.
+```
+
+## Error Handling
+
+Skills handle errors gracefully:
+
+```yaml
+# Skill execution errors are returned to the LLM
+# The LLM can retry or explain the error to the user
+```
+
+Common error scenarios:
+
+1. **Invalid skill slug** - Skill not found in organization
+2. **Code execution errors** - Syntax errors, runtime exceptions
+3. **Missing dependencies** - Required packages not installed
+4. **File I/O errors** - Permission issues, invalid paths
+
+The LLM receives error messages and can:
+
+- Retry with corrected code
+- Explain errors to users
+- Suggest alternatives
+
+## File Output Patterns
+
+### Single File Output
+
+```python
+# Save single file to /output/
+import qrcode
+import os
+
+output_dir = os.environ.get('OUTPUT_DIR', '/output')
+qr = qrcode.QRCode()
+qr.add_data('https://example.com')
+img = qr.make_image()
+img.save(f'{output_dir}/qrcode.png')
+```
+
+### Multiple Files
+
+```python
+# Save multiple files
+import os
+
+output_dir = os.environ.get('OUTPUT_DIR', '/output')
+
+# Generate multiple outputs
+for i in range(3):
+    filename = f'{output_dir}/output_{i}.png'
+    # ... generate file ...
+```
+
+### Structured Output
+
+```python
+# Save structured data + files
+import json
+import os
+
+output_dir = os.environ.get('OUTPUT_DIR', '/output')
+
+# Save metadata
+metadata = {
+    'files': ['chart.png', 'data.csv'],
+    'summary': 'Analysis complete'
+}
+with open(f'{output_dir}/metadata.json', 'w') as f:
+    json.dump(metadata, f)
+
+# Save actual files
+# ... generate chart.png and data.csv ...
+```
+
+## Performance Considerations
+
+### Lazy Initialization
+
+Sandboxes are created only when a skill tool is first called:
+
+```yaml
+# Sandbox not created until LLM calls a skill tool
+agent:
+  skills: [qr-code] # Sandbox created on first use
+```
+
+This means:
+
+- No cost if skills aren't used
+- Fast startup (no sandbox creation delay)
+- Sandbox reused for all skill calls in a trigger
+
+### Timeout Limits
+
+Sandboxes have a 5-minute default timeout:
+
+- **Short operations**: QR codes, simple calculations
+- **Medium operations**: Data analysis, report generation
+- **Long operations**: May need to split into multiple steps
+
+### Sandbox Lifecycle
+
+Each trigger execution gets a fresh sandbox:
+
+- **Clean state** - No leftover files from previous executions
+- **Isolated** - No interference between sessions
+- **Destroyed** - Sandbox cleaned up after trigger completes
+
+## Combining Skills with Tools
+
+Skills and tools can work together:
+
+```yaml
+tools:
+  get-user-data:
+    description: Fetch user data from database
+    parameters:
+      userId: { type: string }
+
+skills:
+  data-analysis:
+    display: description
+    description: Analyzing data
+
+agent:
+  tools: [get-user-data]
+  skills: [data-analysis]
+  agentic: true
+
+handlers:
+  analyze-user:
+    Get user data:
+      block: tool-call
+      tool: get-user-data
+      input:
+        userId: USER_ID
+      output: USER_DATA
+
+    Analyze:
+      block: next-message
+      # LLM can use data-analysis skill with USER_DATA
+```
+
+Pattern:
+
+1. Fetch data via tool (from your backend)
+2. LLM uses skill to analyze/process the data
+3. Generate outputs (files, reports)
+
+## Skill Development Tips
+
+### Writing SKILL.md
+
+Focus on **when** and **how** to use the skill:
+
+```markdown
+---
+name: qr-code
+description: >
+  Generate QR codes from text, URLs, or data. Use when the user needs to create
+  a QR code for any purpose - sharing links, contact information, WiFi credentials,
+  or any text data that should be scannable.
+---
+
+# QR Code Generator
+
+## When to Use
+
+Use this skill when users want to:
+
+- Share URLs easily
+- Provide contact information
+- Create scannable data
+
+## Quick Start
+
+[Clear examples of how to use the skill]
+```
+
+### Script Organization
+
+Organize scripts logically:
+
+```
+skill-name/
+├── SKILL.md
+└── scripts/
+    ├── generate.py      # Main script
+    ├── utils.py         # Helper functions
+    └── requirements.txt # Dependencies
+```
+
+### Error Messages
+
+Provide helpful error messages:
+
+```python
+try:
+    # ... code ...
+except ValueError as e:
+    print(f"Error: Invalid input - {e}")
+    sys.exit(1)
+```
+
+The LLM sees these errors and can retry or explain to users.
+
+## Security Considerations
+
+### Sandbox Isolation
+
+- **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)
+
+### Input Validation
+
+Skills should validate inputs:
+
+```python
+import sys
+
+if not data:
+    print("Error: Data is required")
+    sys.exit(1)
+
+if len(data) > 1000:
+    print("Error: Data too long (max 1000 characters)")
+    sys.exit(1)
+```
+
+### Resource Limits
+
+Be aware of:
+
+- **File size limits** - Large files may fail to upload
+- **Execution time** - 5-minute sandbox timeout
+- **Memory limits** - Sandbox environment constraints
+
+## Debugging Skills
+
+### Check Skill Documentation
+
+The LLM can read skill docs:
+
+```python
+# LLM calls octavus_skill_read to see skill instructions
+```
+
+### Test Locally
+
+Test skills before uploading:
+
+```bash
+# Test skill locally
+python scripts/generate.py --data "test"
+```
+
+### Monitor Execution
+
+Check execution logs in the platform debug view:
+
+- Tool calls and arguments
+- Code execution results
+- File outputs
+- Error messages
+
+## Common Patterns
+
+### Pattern 1: Generate and Return
+
+```yaml
+# User asks for QR code
+# LLM generates QR code
+# File automatically available for download
+```
+
+### Pattern 2: Analyze and Report
+
+```yaml
+# User provides data
+# LLM analyzes with skill
+# Generates report file
+# Returns summary + file link
+```
+
+### Pattern 3: Transform and Save
+
+```yaml
+# User uploads file (via tool)
+# LLM processes with skill
+# Generates transformed file
+# Returns new file link
+```
+
+## Best Practices Summary
+
+1. **Enable only needed skills** - Don't overwhelm the LLM
+2. **Choose appropriate display modes** - Match user experience needs
+3. **Write clear skill descriptions** - Help LLM understand when to use
+4. **Handle errors gracefully** - Provide helpful error messages
+5. **Test skills locally** - Verify before uploading
+6. **Monitor execution** - Check logs for issues
+7. **Combine with tools** - Use tools for data, skills for processing
+8. **Consider performance** - Be aware of timeouts and limits
+
+## Next Steps
+
+- [Skills](/docs/protocol/skills) - Basic skills documentation
+- [Agent Config](/docs/protocol/agent-config) - Configuring skills
+- [Tools](/docs/protocol/tools) - External tools integration