Skill Variants

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

Variant	Badge	Permissions	Use Case
Read Only	Safe	Read, list, search only	Log monitoring, configuration reading
Full Access	Recommended (Default)	Read, write, create, delete	General file operations, log writing
Sandboxed	Secure	Isolated to /sandbox directory	Testing, untrusted operations

Shell Variants

Variant	Badge	Permissions	Use Case
Safe Commands	Safe (Default)	ls, cat, grep, find, ps, etc.	System monitoring, diagnostics
Full Access	Advanced	All commands	Administrative tasks, deployments
Read Only	Secure	Non-destructive commands only	Auditing, investigation

Agent Communication Variants

Variant	Badge	Permissions	Use Case
Read Only	Safe	Status monitoring only	Execution tracking, observability
Limited	Recommended (Default)	Specific agents/teams, depth=2	Standard orchestration, delegation
Full Orchestration	Advanced	All agents/teams, depth=5	Complex 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:

Choose a Skill Type: Select from the built-in Skills (or create a custom Skill)
Select a Variant: Pick the variant that matches your security requirements
Customize Configuration: Adjust settings like timeouts, allowed commands, or directories
Name the Instance: Give it a descriptive name (e.g., “Production File System”, “Dev Shell”)
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

Introduction

Quick Start

Web Interface

Core Concepts

Infrastructure

Skill Variants

Why Use Variants?

How Variants Work

Variant Examples

File System Variants

Shell Variants

Agent Communication Variants

Configuration Differences Between Variants

Locked vs. Overridable Settings

Variant Configuration Guide

Creating a Skill Instance

Example: Creating Multiple Instances

Dynamic Configuration & Layering

Configuration Precedence Example

Practical Use Cases

Dynamic Configuration Guide

Variant Configuration

Dynamic Configuration

Built-in Skills

CLI Reference

Examples

Overview

​Why Use Variants?

​How Variants Work

​Variant Examples

​File System Variants

​Shell Variants

​Agent Communication Variants

​Configuration Differences Between Variants

​Locked vs. Overridable Settings

Variant Configuration Guide

​Creating a Skill Instance

​Example: Creating Multiple Instances

​Dynamic Configuration & Layering

​Configuration Precedence Example

​Practical Use Cases

Dynamic Configuration Guide

​Related Pages

Variant Configuration

Dynamic Configuration

Built-in Skills

CLI Reference

Examples

Overview

Why Use Variants?

How Variants Work

Variant Examples

File System Variants

Shell Variants

Agent Communication Variants

Configuration Differences Between Variants

Locked vs. Overridable Settings

Creating a Skill Instance

Example: Creating Multiple Instances

Dynamic Configuration & Layering

Configuration Precedence Example

Practical Use Cases

Related Pages