> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Skill Variants
> Learn how to use pre-configured Skill variants to create secure, permission-appropriate skill instances following the principle of least privilege.
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
```bash theme={null}
# 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](/core-concepts/skills/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:**
```json theme={null}
// ✅ 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
}
}
```
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:
```bash theme={null}
# 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
```json theme={null}
// 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:**
```json theme={null}
// 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:**
```json theme={null}
// 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
}
}
```
Learn about configuration inheritance, override precedence, environment variables, and team/agent-specific configurations
Use `kubiya skill get --effective-config --agent ` to see the final resolved configuration after all layers are applied.
## **Related Pages**
Detailed configuration matrices and customization guide
Configuration inheritance, layering, and runtime overrides
See all available Skills and their variants
Command-line tools for creating skill instances
Real-world variant selection examples
Back to Skills overview