Skip to main content
Skill variants are pre-configured templates that provide different levels of access and functionality for the same Skill type. Instead of configuring a Skill from scratch, you can select a variant that matches your security and functional requirements.

​
Why Use Variants?

Variants follow the principle of least privilege by offering pre-configured permission sets:
  • Safe/Read-Only Variants: Minimal permissions for monitoring and read-only operations
  • Common/Limited Variants (usually default): Balanced permissions suitable for most use cases
  • Advanced/Full Access Variants: Maximum permissions for power users and automation
Selecting the appropriate variant is crucial for maintaining security. Start with the most restrictive variant that meets your needs.

​
How Variants Work

When creating a Skill, you can choose from available variants in the UI or CLI: UI: Select a variant from the “Template Option” dropdown when creating a Skill CLI: Use the --variant flag when creating a Skill 
# Create a read-only file system skill
kubiya skill create --name "Logs Reader" --type file_system --variant read_only

# Create a full access shell skill
kubiya skill create --name "Admin Shell" --type shell --variant full_access

​
Variant Examples

​
File System Variants

VariantBadgePermissionsUse Case
Read OnlySafeRead, list, search onlyLog monitoring, configuration reading
Full AccessRecommended (Default)Read, write, create, deleteGeneral file operations, log writing
SandboxedSecureIsolated to /sandbox directoryTesting, untrusted operations

​
Shell Variants

VariantBadgePermissionsUse Case
Safe CommandsSafe (Default)ls, cat, grep, find, ps, etc.System monitoring, diagnostics
Full AccessAdvancedAll commandsAdministrative tasks, deployments
Read OnlySecureNon-destructive commands onlyAuditing, investigation

​
Agent Communication Variants

VariantBadgePermissionsUse Case
Read OnlySafeStatus monitoring onlyExecution tracking, observability
LimitedRecommended (Default)Specific agents/teams, depth=2Standard orchestration, delegation
Full OrchestrationAdvancedAll agents/teams, depth=5Complex multi-agent workflows
See all built-in Skills and their available variants in the Built-in Skills reference.

​
Configuration Differences Between Variants

Variants differ not just in permissions, but in their configuration defaults and what settings can be overridden.

​
Locked vs. Overridable Settings

Locked Settings enforce the variant’s security model and cannot be changed:
  • Read Only variants: Cannot enable write operations (enable_save_file, enable_delete)
  • Sandboxed variants: Cannot change base_dir (prevents sandbox escape)
  • Safe Commands variants: Cannot add destructive commands to allowed list
Overridable Settings can be customized within the variant’s security boundaries:
  • Timeouts, memory limits, CPU limits
  • File extensions, directories (within security constraints)
  • Specific command lists (within allowed operations)
Example: 
// ✅ Allowed: Increase timeout on Read Only variant
{
  "variant": "read_only",
  "configuration": {
    "timeout": 120
  }
}

// ❌ Blocked: Cannot enable writes on Read Only variant
{
  "variant": "read_only",
  "configuration": {
    "enable_save_file": true  // Will be rejected - violates security model
  }
}

Variant Configuration Guide

See detailed configuration matrices showing what each variant allows and how to customize within boundaries

​
Creating a Skill Instance

A Skill instance is a named, configured version of a Skill type with a specific variant and custom configuration. Steps to create a Skill instance:
  1. Choose a Skill Type: Select from the built-in Skills (or create a custom Skill)
  2. Select a Variant: Pick the variant that matches your security requirements
  3. Customize Configuration: Adjust settings like timeouts, allowed commands, or directories
  4. Name the Instance: Give it a descriptive name (e.g., “Production File System”, “Dev Shell”)
  5. Assign to Entities: Attach the Skill instance to agents, teams, or environments

​
Example: Creating Multiple Instances

You can create multiple instances of the same Skill type with different configurations: 
# Read-only file system for monitoring
kubiya skill create --name "Logs Monitor" --type file_system --variant read_only

# Full-access file system for deployment
kubiya skill create --name "Deploy Manager" --type file_system --variant full_access

# Sandboxed file system for testing
kubiya skill create --name "Test Sandbox" --type file_system --variant sandboxed --config-json '{"base_dir":"/tmp/test"}'
Each instance has its own configuration, permissions, and can be assigned to different agents or teams independently.

​
Dynamic Configuration & Layering

Kubiya uses a 4-layer configuration model where each layer can override settings from the previous layer: 
1. Variant Defaults (base template)
   ↓  Inherits & Overrides
2. Skill Instance Config (your customization)
   ↓  Inherits & Overrides
3. Entity-Level Config (team/agent/environment)
   ↓  Inherits & Overrides
4. Runtime Config (execution-time overrides)
   ↓
FINAL EFFECTIVE CONFIGURATION

​
Configuration Precedence Example

// Layer 1: Variant Defaults (file_system - full_access)
{
  "enable_read_file": true,
  "enable_save_file": true,
  "base_dir": "/",
  "timeout": 60
}

// Layer 2: Skill Instance (your customization)
{
  "base_dir": "/opt/myapp",  // Overrides layer 1
  "allowed_extensions": ["yaml", "json"]  // New setting
}

// Layer 3: Team-Level Override
{
  "timeout": 120,  // Overrides layers 1 & 2
  "base_dir": "/team/workspace"  // Overrides layers 1 & 2
}

// Layer 4: Runtime (agent execution)
{
  "base_dir": "/opt/myapp/production"  // Overrides all layers
}

// FINAL EFFECTIVE CONFIG:
{
  "enable_read_file": true,              // From layer 1 (variant)
  "enable_save_file": true,              // From layer 1 (variant)
  "base_dir": "/opt/myapp/production",   // From layer 4 (runtime) ← HIGHEST
  "timeout": 120,                        // From layer 3 (team)
  "allowed_extensions": ["yaml", "json"] // From layer 2 (instance)
}
Last Layer Wins: When the same setting appears in multiple layers, the highest layer (closest to runtime) takes precedence.

​
Practical Use Cases

Environment-Specific Configuration: 
// Skill instance uses environment variables
{
  "configuration": {
    "base_dir": "{{ENVIRONMENT_BASE_DIR}}",  // Variable reference
    "timeout": "{{TIMEOUT_SECONDS:60}}"      // With default fallback
  }
}

// Development: ENVIRONMENT_BASE_DIR=/dev, TIMEOUT_SECONDS=600
// Production: ENVIRONMENT_BASE_DIR=/prod, TIMEOUT_SECONDS=60
Team-Level Overrides: 
// Platform team gets higher limits
{
  "team_overrides": {
    "timeout": 300,
    "max_concurrent": 10
  }
}

// Security team gets more restrictive settings
{
  "team_overrides": {
    "allowed_extensions": ["yaml"],
    "timeout": 60
  }
}

Dynamic Configuration Guide

Learn about configuration inheritance, override precedence, environment variables, and team/agent-specific configurations
Use kubiya skill get <skill-id> --effective-config --agent <agent-id> to see the final resolved configuration after all layers are applied.

Variant Configuration

Detailed configuration matrices and customization guide

Dynamic Configuration

Configuration inheritance, layering, and runtime overrides

Built-in Skills

See all available Skills and their variants

CLI Reference

Command-line tools for creating skill instances

Examples

Real-world variant selection examples

Overview

Back to Skills overview