Skip to main content
Variants are pre-configured templates that provide different security levels and default configurations for each skill type. Understanding how variants differ helps you choose and customize the right configuration for your use case.

​
Configuration Inheritance Model

Skills follow a hierarchical configuration model: 
Skill Type (base capabilities)
  └── Variant (security template + defaults)
      └── Skill Instance (your customizations)
          └── Runtime (environment overrides)
Each layer inherits from the previous and can override specific settings within security boundaries.

​
Variant Configuration Matrices

​
File System Skill

ConfigurationRead Only 🟢Full Access 🟡Sandboxed 🔵
enable_read_file✅ true✅ true✅ true
enable_save_file❌ false (locked)✅ true✅ true
enable_list_files✅ true✅ true✅ true
enable_search_files✅ true✅ true✅ true
base_dir”/""/""/sandbox” (locked)
Can Override?LimitedYesMedium
Locked Settings:
  • Read Only: Cannot enable write operations (enable_save_file)
  • Sandboxed: Cannot change base_dir (prevents sandbox escape)

​
Shell Skill

ConfigurationSafe Commands 🟢Full Access 🔴Read Only 🟢
allowed_commandsPre-defined safe list["*"] (all)View-only commands
blocked_commandsDestructive ops[] (none)All except allowed
timeout30s300s30s
Can Override?YesYesLimited
Locked Settings:
  • Safe Commands: Cannot add destructive commands to allowed list
  • Read Only: Cannot enable write operations

​
Python Skill

ConfigurationRestricted Imports 🟢Full Access 🔴
allowed_importsSafe std library modules["*"] (unrestricted)
max_memory”512MB""2GB”
timeout120s600s
Can Override?YesYes

​
Docker Skill

ConfigurationContainers Only 🟡Full Control 🔴
allowed_operationsContainer lifecycleAll operations
network_accessLimitedFull
volume_management❌ false✅ true
Can Override?YesYes

​
Agent Communication Skill

ConfigurationRead Only 🟢Limited 🟡Full Orchestration 🔴
allowed_operationsStatus onlyExecute + statusAll operations
allowed_agentsN/AWhitelist required["*"] (all)
max_execution_depthN/A25
Can Override?NoYesYes

​
Customizing Variants

​
Using CLI with —variant Flag

# Start with variant template, then customize
kubiya skill create \
  --name "Custom Production Files" \
  --type file_system \
  --variant full_access \
  --config-json '{
    "base_dir": "/opt/production",
    "allowed_extensions": ["yaml", "json", "log"],
    "max_file_size": "10MB"
  }' \
  --enabled

​
Understanding Locked vs. Overridable Settings

These settings enforce the variant’s security model and cannot be changed:Read Only Variants:
  • Any write-enabling flags (enable_save_file, enable_delete)
  • Destructive command permissions
Sandboxed Variants:
  • base_dir (prevents escaping the sandbox)
  • Network access restrictions
Attempting to override locked settings will result in validation errors.
These settings can be customized within the variant’s boundaries:Performance Settings:
  • Timeouts, memory limits, CPU limits
  • Concurrency limits
Scope Settings:
  • File extensions (within allowed operations)
  • Directories (within base_dir restrictions)
  • Specific command lists (within security boundaries)
Behavioral Settings:
  • Retry counts, delays
  • Caching options
  • Logging levels

​
Configuration Validation

When you create or update a skill instance, Kubiya validates your configuration: 
Configuration Override Attempt
  ↓
1. Does it violate variant security model?
   ↓ No
2. Is the value within acceptable range?
   ↓ Yes
3. Is the setting marked as overridable?
   ↓ Yes
4. ✅ Override Applied
Validation Failures: 
# ❌ Attempting to enable writes on Read Only variant
kubiya skill create --type file_system --variant read_only \
  --config-json '{"enable_save_file": true}'

Error: Cannot override locked setting 'enable_save_file' for variant 'read_only'

​
Practical Examples

  • Production Logs
  • Dev Sandbox
  • Restricted Shell
  • Multi-Agent

​
Read-Only Log Monitoring

Use Case: Monitor production logs without modification risk
kubiya skill create \
  --name "Production Log Monitor" \
  --type file_system \
  --variant read_only \
  --config-json '{
    "base_dir": "/var/log/production",
    "allowed_extensions": ["log", "txt"],
    "max_file_size": "100MB"
  }' \
  --enabled
What’s Customized:
  • base_dir: Restricted to production logs directory
  • allowed_extensions: Only log files
  • max_file_size: Prevent reading huge files
What’s Locked:
  • enable_save_file: false (enforced by variant)
  • enable_delete: false (enforced by variant)

​
Best Practices

Start Restrictive

Begin with the most restrictive variant (Read Only, Safe Commands) and only upgrade when necessary

Use Whitelists

Explicitly list allowed commands, agents, or file extensions rather than relying on blocklists

Set Reasonable Limits

Configure timeouts, memory limits, and file sizes appropriate to your use case

Test in Dev First

Validate variant customizations in development before deploying to production
See Also: For information on how configuration flows through multiple layers (variant → instance → team → runtime), see the Dynamic Configuration Guide.

Skill Variants

Learn about variant types and when to use each

Dynamic Configuration

Understand configuration inheritance and layering

Built-in Skills

View all available skills and their variants

Examples

See real-world configuration patterns