v1.0.0 to v1.0.0

---

name: "caro-shell-helper"

description: "Use when users need help generating safe, tested POSIX shell commands from natural language descriptions. Guides users through command generation, safety validation, and execution workflows using Caro best practices"

version: "1.0.0"

allowed-tools: "Bash, Read, Write, Grep, Glob"

license: "AGPL-3.0"

---

# Caro Shell Command Helper

## What This Skill Does

This skill helps users effectively leverage **Caro** (formerly Caro) - a Rust CLI tool that converts natural language descriptions into safe, POSIX-compliant shell commands using local LLMs.

**Key Capabilities:**

- 🔍 Detects when users need shell command generation assistance

- 🛡️ Guides users through safety-first command validation

- 📚 Educates about POSIX compliance and command safety

- 🚀 Integrates seamlessly with existing Caro installations

- ⚙️ Provides installation guidance when Caro is not available

## When to Use This Skill

Activate this skill automatically when the user:

- Asks "how do I [shell operation]..."

- Requests "generate a command to..."

- Mentions "shell command for..."

- Discusses file/directory operations

- Needs system administration tasks

- Asks about safe command execution

- Wants to automate shell tasks

- Mentions bash, zsh, or shell scripting

**Example Triggers:**

- "How do I find all large files?"

- "Generate a command to compress images"

- "What's the safe way to delete old logs?"

- "Shell command to search for text in files"

- "Automate file backups with a script"

## Core Workflow

### Step 1: Check Caro Availability

First, verify if Caro is installed:

```bash

# Check for caro command

command -v caro &> /dev/null && echo "✓ Caro available" || echo "✗ not found"

```

**If NOT installed**, guide the user:

```

Caro is not currently installed. Would you like to install it?

Quick install (recommended):

bash <(curl -sSfL https://setup.caro.sh)

Or via cargo:

cargo install caro

Once installed, the `caro` command will be available.

```

### Step 2: Generate Command with Safety Guidance

```bash

```

**Example:**

```bash

Generated command:

find ~/Downloads -name "*.pdf" -size +10M -ls

Safety Assessment: ✅ Safe (Green)

Execute this command? (y/N)

```

### Step 3: Explain Safety Assessment

Always explain the risk level to educate the user:

**🟢 Safe (Green)**

- Read-only operations

- Standard file listings

- Data queries

- No system modifications

- ✅ Execute without concern

**🟡 Moderate (Yellow)**

- File modifications

- Package operations

- Non-critical deletions

- ⚠️ Review before executing

**🟠 High (Orange)**

- Recursive deletions

- Mass file operations

- System configuration changes

- ⚠️ Carefully review and confirm

**🔴 Critical (Red)**

- System destruction patterns (`rm -rf /`)

- Disk operations (`mkfs`, `dd`)

- Fork bombs

- Privilege escalation

- 🛑 BLOCKED or requires explicit override

### Step 4: POSIX Compliance Education

Emphasize why POSIX compliance matters:

```

✓ POSIX-Compliant Command:

find ~/Downloads -name "*.pdf" -size +10M

This works on: bash, zsh, sh, dash, ksh (all POSIX shells)

✗ Bash-Specific (Non-Portable):

find ~/Downloads -name "*.pdf" -size +10M -print0 | xargs -0 ls -lh

Problem: -print0 is not POSIX standard

Better: Use -exec for portability

```

### Step 5: Command Execution Guidance

After Caro generates a command, guide the user:

1. **Review the command**: "Do you understand what each part does?"

2. **Check safety level**: "This is a [risk level] operation"

3. **Verify scope**: "Will this affect the files/directories you intend?"

4. **Test safely**: "Try with a small subset first, or use --dry-run if available"

5. **Execute**: "Ready to run? The command will execute when you confirm"

## Safety Patterns to Highlight

### Always Block These Patterns

**System Destruction:**

```bash

rm -rf / # Deletes entire filesystem

rm -rf ~ # Deletes home directory

rm -rf /* # Same as rm -rf /

```

**Fork Bombs:**

```bash

:(){ :|:& };: # Creates infinite processes

```

**Disk Operations:**

```bash

mkfs /dev/sda # Formats disk (destroys data)

dd if=/dev/zero of=/dev/sda # Overwrites disk

```

**Privilege Escalation:**

```bash

sudo su # Gains root access

chmod 777 / # Makes root world-writable

```

### Suggest Safe Alternatives

When users request dangerous operations, suggest safer alternatives:

**User wants:** "Delete all log files"

**Dangerous:** `rm -rf /var/log/*`

**Safe alternative:**

```bash

# First, preview what will be deleted

find /var/log -name "*.log" -type f -mtime +30 -ls

# Then delete only old logs with confirmation

find /var/log -name "*.log" -type f -mtime +30 -exec rm -i {} \;

```

**User wants:** "Clean up temp files"

**Dangerous:** `rm -rf /tmp/*`

**Safe alternative:**

```bash

# Use tmpwatch or tmpreaper (proper cleanup tools)

tmpwatch 24 /tmp

# Or manually with safety checks

find /tmp -type f -mtime +7 -user $(whoami) -delete

```

## Backend Configuration Guidance

Caro supports multiple inference backends. Help users choose:

- **Model**: Qwen2.5-Coder-1.5B-Instruct (quantized)

- **Setup**: Works out-of-the-box after installation

### Ollama Backend

- **Best for**: Local model control, privacy-focused users

- **Advantages**: Many model choices, easy model management

- **Setup**:

```toml

# ~/.config/caro/config.toml

[backend]

primary = "ollama"

[backend.ollama]

base_url = "http://localhost:11434"

model_name = "codellama:7b"

```

### vLLM Backend

- **Best for**: High-performance inference, server deployments

- **Advantages**: Optimized for throughput, production-ready

- **Setup**:

```toml

[backend]

primary = "vllm"

[backend.vllm]

base_url = "http://localhost:8000"

model_name = "codellama/CodeLlama-7b-hf"

```

## Usage Examples

### Example 1: Finding Files

**User:** "I need to find all Python files modified in the last week"

**Response:**

```

Generated command:

find . -name "*.py" -type f -mtime -7

Safety Assessment: ✅ Safe (Green)

- Read-only operation

- POSIX-compliant syntax

- Searches current directory and subdirectories

Explanation:

- find . : Search from current directory

- -name "*.py" : Match files ending in .py

- -type f : Only regular files (not directories)

- -mtime -7 : Modified within last 7 days

Execute? (y/N)

```

### Example 2: Safe Deletion

**User:** "Delete all .log files older than 30 days"

**Response:**

```

Generated command:

find . -name "*.log" -type f -mtime +30 -delete

Safety Assessment: 🟠 High (Orange)

- Performs deletion (irreversible)

- Recursive operation

- Affects multiple files

⚠️ SAFETY RECOMMENDATION:

Preview what will be deleted first:

$ find . -name "*.log" -type f -mtime +30 -ls

Review the list, then if it looks correct, run with -delete.

Better yet, use interactive deletion:

$ find . -name "*.log" -type f -mtime +30 -exec rm -i {} \;

This will ask for confirmation on each file.

Proceed with preview? (y/N)

```

### Example 3: System Operations

**User:** "How do I check disk space?"

**Response:**

```

Generated command:

df -h

Safety Assessment: ✅ Safe (Green)

- Read-only operation

- Standard system utility

- No modifications

Explanation:

- df : Disk free - shows filesystem disk space usage

- -h : Human-readable format (GB, MB instead of bytes)

This is completely safe to run. Execute? (y/N)

```

## Advanced Features

### Multi-Step Workflows

For complex tasks, break them into steps:

**User:** "Find large files and compress them"

**Response:**

```

Step 1: Find large files (>100MB)

find . -type f -size +100M -ls

Step 2: Review the list (don't automate yet)

[User reviews output]

Step 3: Compress specific files

gzip -k file.txt

The -k flag keeps the original file as a backup.

Would you like to proceed with step 1?

```

### Configuration Customization

Help users customize Caro behavior:

```toml

# ~/.config/caro/config.toml

[safety]

enabled = true

level = "moderate" # strict, moderate, or permissive

require_confirmation = true

[output]

format = "plain" # json, yaml, or plain

color = true

[backend]

enable_fallback = true

```

## Educational Notes

### Why POSIX Compliance Matters

```

POSIX-compliant commands work across:

- ✓ bash (most common)

- ✓ zsh (macOS default since Catalina)

- ✓ sh (minimal, universal)

- ✓ dash (Debian/Ubuntu default /bin/sh)

- ✓ ksh (Korn shell)

Non-POSIX features that break portability:

- Bash arrays: myarray=(one two three)

- Process substitution: <(command)

- Extended globbing: shopt -s extglob

- [[ ]] conditional (use [ ] instead)

Caro generates POSIX-compliant commands by default for maximum portability.

```

### Risk Assessment Philosophy

```

Caro uses a 4-tier risk model:

1. Safe (Green): Read-only, no system impact

- Listings, searches, queries

- Safe to execute without review

2. Moderate (Yellow): Limited modifications

- File edits, package updates

- Review recommended

3. High (Orange): Significant changes

- Deletions, mass operations

- Careful review required

4. Critical (Red): Dangerous operations

- System destruction, privilege escalation

- Blocked or requires explicit override

This helps users develop safety intuition over time.

```

## Troubleshooting

### Caro Not Found

```bash

# Add cargo bin to PATH

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

source ~/.bashrc

```

### Command Generation Fails

```bash

# Check Caro status

caro --version

# Enable verbose mode for debugging

caro --verbose "your prompt here"

# Try different backend

```

### Safety Validation Too Strict

```toml

# Adjust in ~/.config/caro/config.toml

[safety]

level = "permissive" # or "moderate"

```

## Best Practices Summary

1. **Always check if Caro is installed** before suggesting usage

2. **Explain risk levels** to educate users about command safety

3. **Highlight POSIX compliance** for portable, reliable commands

4. **Suggest preview before execution** for destructive operations

5. **Break complex tasks into steps** for safety and clarity

6. **Provide safe alternatives** to dangerous commands

7. **Educate, don't just execute** - help users learn command safety

## Resources

- **Caro Repository**: https://github.com/wildcard/caro

- **Website**: https://caro.sh

- **Installation Guide**: https://caro.sh/install

- **Safety Patterns**: See `references/safety-patterns.md`

- **POSIX Reference**: See `references/posix-compliance.md`

## Remember

The goal is not just to generate commands, but to help users:

- ✅ Understand what commands do

- ✅ Recognize dangerous patterns

- ✅ Develop safety-first habits

- ✅ Write portable, POSIX-compliant scripts

- ✅ Make informed decisions about command execution

Always prioritize user education and safety over convenience.