> ## 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.
# Shell Skill
> Execute shell commands on the worker with configurable command restrictions and security controls.
`shell`
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 diagnostics**
Execute health checks, performance monitoring, and system analysis
**Executing deployment scripts**
Run deployment workflows, configuration updates, and releases
**Querying system information**
Gather OS details, disk usage, network status, and resource metrics
**Process management**
Start, 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](/core-concepts/skills/variant-configuration) for detailed differences.
***
## Configuration
**Example Configuration:**
```json theme={null}
{
"allowed_commands": ["ps", "top", "df", "free", "netstat"],
"timeout": 60,
"max_output_size": "5MB",
"working_directory": "/opt"
}
```
| 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 |
**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](/core-concepts/skills/variant-configuration)
***
## Quick Start
```bash theme={null}
# Create skill with variant
kubiya skill create --name "System Monitor" --type shell --variant safe_commands --enabled
# Associate with agent
kubiya skill associate agent
```
See full production deployment patterns, CI/CD configurations, and troubleshooting guides
***
## Command Patterns
### Wildcards and Subcommands
You can use patterns to allow command families:
```json theme={null}
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:
```json theme={null}
# 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
Explicitly specify `allowed_commands` rather than relying on `blocked_commands`. Whitelisting is more secure than blacklisting.
```json theme={null}
# Good: Whitelist approach
"allowed_commands": ["ls", "cat", "grep"]
# Risky: Blacklist approach (easy to miss dangerous commands)
blocked_commands: ["rm", "dd"]
```
Always configure command timeouts to prevent runaway processes.
```json theme={null}
"timeout": 60 automatically terminate after 60 seconds
```
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.
***
## Troubleshooting & Related Skills
**Solutions:**
* Verify command is installed on worker system
* Check `PATH` environment variable includes command location
* Use full path: `/usr/bin/kubectl` instead of `kubectl`
**Solutions:**
* Ensure worker process user has OS-level permissions
* Check file permissions on scripts or binaries
* Verify `working_directory` is accessible
**Solutions:**
* Check exact command string matches (including subcommands)
* Verify no `blocked_commands` override
* Use `"*"` wildcard for command families: `"git*"`
### Related Skills
Access files for scripts and configurations
Execute Python scripts as alternative to shell
Specialized Docker command management
Return to built-in skills overview