Shell Skill

Type

shell

Variants

Safe Commands, Full Access, Read Only

Purpose: The Shell skill enables agents to execute shell commands on the worker system with fine-grained control over which commands are permitted.

Common Use Cases

Running system diagnosticsExecute health checks, performance monitoring, and system analysis

Executing deployment scriptsRun deployment workflows, configuration updates, and releases

Querying system informationGather OS details, disk usage, network status, and resource metrics

Process managementStart, stop, monitor, and manage system processes

Variants Overview

Variant	Security	Key Permissions	Best For	Create Command
Safe Commands 🟢	Safe	Pre-approved safe commands only	System monitoring, diagnostics	`--variant safe_commands`
Full Access 🔴	Unrestricted	Execute any shell command	Admin tasks, deployments	`--variant full_access`
Read Only 🟢	Secure	View-only commands (ls, cat, grep)	Auditing, compliance checks	`--variant read_only`

Choosing a variant: Start with Safe Commands or Read Only, upgrade to Full Access only when absolutely necessary. See Variant Configuration for detailed differences.

Configuration

Example Configuration:

{
  "allowed_commands": ["ps", "top", "df", "free", "netstat"],
  "timeout": 60,
  "max_output_size": "5MB",
  "working_directory": "/opt"
}

📋 Full Configuration Reference

Parameter	Type	Default	Description
`allowed_commands`	array	variant-specific	Whitelist of permitted commands
`blocked_commands`	array	variant-specific	Blacklist of forbidden commands
`timeout`	number	60	Command timeout in seconds
`max_output_size`	string	”10MB”	Maximum output capture size
`working_directory`	string	”/“	Default command working directory
`environment_variables`	object	Custom environment variables

⚙️ Variant-Specific Defaults

Safe Commands:

allowed_commands: [“ls”, “cat”, “grep”, “find”, “ps”, “top”, “df”, “echo”, “git status”, …]
blocked_commands: [“rm”, “dd”, “mkfs”, “sudo”, “chmod”, “chown”]

Full Access:

allowed_commands: [”*”] (all commands)
blocked_commands: [] (none blocked)

Read Only:

allowed_commands: [“ls”, “cat”, “grep”, “find”, “ps”, “top”, “df”, “free”]
All write operations blocked

See: Variant Configuration Guide

Quick Start

# Create skill with variant
kubiya skill create --name "System Monitor" --type shell --variant safe_commands --enabled

# Associate with agent
kubiya skill associate agent <agent-id> <skill-id>

View Complete Examples

See full production deployment patterns, CI/CD configurations, and troubleshooting guides

Command Patterns

Wildcards and Subcommands

You can use patterns to allow command families:

allowed_commands:
  - "git*"              # Allows all git subcommands
  - "kubectl get"       # Allows only kubectl get
  - "docker ps"         # Allows only docker ps
  - "systemctl status"  # Allows only status checks

Environment Variable Expansion

Commands can reference environment variables:

# In configuration
environment_variables:
  DEPLOY_ENV: "production"
  APP_NAME: "myapp"

# Agent can use these in commands
# echo "Deploying ${APP_NAME} to ${DEPLOY_ENV}"

Security Best Practices

Use Command Whitelisting

Explicitly specify allowed_commands rather than relying on blocked_commands. Whitelisting is more secure than blacklisting.

# Good: Whitelist approach
"allowed_commands": ["ls", "cat", "grep"]

# Risky: Blacklist approach (easy to miss dangerous commands)
blocked_commands: ["rm", "dd"]

Set Reasonable Timeouts

Always configure command timeouts to prevent runaway processes.

"timeout": 60 automatically terminate after 60 seconds

Avoid Full Access in Production

Use Safe Commands variant for production. Reserve Full Access for development or isolated admin tasks.

Full Access variant should be used with caution. Prefer Safe Commands for production environments.

Command Not Found

Solutions:

Verify command is installed on worker system
Check PATH environment variable includes command location
Use full path: /usr/bin/kubectl instead of kubectl

Permission Denied

Solutions:

Ensure worker process user has OS-level permissions
Check file permissions on scripts or binaries
Verify working_directory is accessible

Command Blocked Unexpectedly

Solutions:

Check exact command string matches (including subcommands)
Verify no blocked_commands override
Use "*" wildcard for command families: "git*"

File System Skill

Access files for scripts and configurations

Python Skill

Execute Python scripts as alternative to shell

Docker Skill

Specialized Docker command management

View All Skills

Return to built-in skills overview

Introduction

Quick Start

Web Interface

Core Concepts

Infrastructure

Type

Variants

Common Use Cases

Variants Overview

Configuration

Quick Start

View Complete Examples

Command Patterns

Wildcards and Subcommands

Environment Variable Expansion

Security Best Practices

File System Skill

Python Skill

Docker Skill

View All Skills

Type

Variants

​Common Use Cases

​Variants Overview

​Configuration

​Quick Start

View Complete Examples

​Command Patterns

​Wildcards and Subcommands

​Environment Variable Expansion

​Security Best Practices

​Troubleshooting & Related Skills

​Related Skills

File System Skill

Python Skill

Docker Skill

View All Skills

Common Use Cases

Variants Overview

Configuration

Quick Start

Command Patterns

Wildcards and Subcommands

Environment Variable Expansion

Security Best Practices

Troubleshooting & Related Skills

Related Skills