caro-shell-helper

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

Default Backend: Claude Haiku 4.5

IMPORTANT: When this skill is used within Claude Code, always use the Claude backend by default. This provides the fastest response times and best accuracy.

# Default command format when running in Claude Code
caro --backend claude "user's request here"

The Claude backend uses claude-haiku-4-5-20251101 for fast, cost-effective command generation. The API key is automatically provided by Claude Code.

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:

# 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

When the user describes what they need, use Caro with the Claude backend (default for Claude Code):

# Always use --backend claude when running in Claude Code
caro --backend claude "user's natural language description"

Example:

$ caro --backend claude "find all PDF files larger than 10MB in Downloads"

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

Safety Assessment: ✅ Safe (Green)
Backend: Claude (claude-haiku-4-5-20251101)
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:

rm -rf /          # Deletes entire filesystem
rm -rf ~          # Deletes home directory
rm -rf /*         # Same as rm -rf /

Fork Bombs:

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

Disk Operations:

mkfs /dev/sda     # Formats disk (destroys data)
dd if=/dev/zero of=/dev/sda  # Overwrites disk

Privilege Escalation:

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:

# 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:

# 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:

Claude Backend (Default for Claude Code)

• Best for: Running directly within Claude Code or with Anthropic API access
• Advantages: Fastest, most accurate, uses Claude Haiku 4.5 by default
• Model: claude-haiku-4-5-20251101 (default)
• Setup:

  # ~/.config/caro/config.toml
  [backend]
  primary = "claude"
  
  [backend.claude]
  model_name = "claude-haiku-4-5-20251101"  # Fast and cost-effective
  # API key read from ANTHROPIC_API_KEY environment variable
  

When running in Claude Code: The Claude backend is automatically preferred as it provides the best integration and fastest response times. No additional configuration is needed - Claude Code provides the API key automatically.

Embedded Backend (Default for Standalone)

• Best for: Apple Silicon Macs (M1/M2/M3/M4), offline usage
• Advantages: No external dependencies, works offline
• 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:

  # ~/.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:

  [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:

I'll help you generate a safe command using Caro with Claude Haiku 4.5.

$ caro --backend claude "find all Python files modified in the last week"

Generated command:
  find . -name "*.py" -type f -mtime -7

Safety Assessment: ✅ Safe (Green)
Backend: Claude (claude-haiku-4-5-20251101)
- 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:

This involves deletion, so let's be careful. I'll use Caro with Claude Haiku 4.5.

$ caro --backend claude "delete all .log files older than 30 days"

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

Safety Assessment: 🟠 High (Orange)
Backend: Claude (claude-haiku-4-5-20251101)
- 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:

$ caro --backend claude "check disk space for all mounted filesystems"

Generated command:
  df -h

Safety Assessment: ✅ Safe (Green)
Backend: Claude (claude-haiku-4-5-20251101)
- 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:

This is a multi-step operation. Let's do it safely using Claude Haiku 4.5:

Step 1: Find large files (>100MB)
$ caro --backend claude "find files larger than 100MB"
  find . -type f -size +100M -ls

Step 2: Review the list (don't automate yet)
[User reviews output]

Step 3: Compress specific files
$ caro --backend claude "compress file.txt with gzip"
  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:

# ~/.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]
primary = "claude"  # claude (default in Claude Code), embedded, ollama, or vllm
enable_fallback = true

[backend.claude]
model_name = "claude-haiku-4-5-20251101"  # Fast and cost-effective
# API key read from ANTHROPIC_API_KEY environment variable

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

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

Command Generation Fails

# Check Caro status
caro --version

# Enable verbose mode for debugging
caro --verbose "your prompt here"

# Try different backend
caro --backend claude "your prompt here"   # Use Claude Haiku 4.5 (fastest)
caro --backend ollama "your prompt here"   # Use local Ollama
caro --backend embedded "your prompt here" # Use embedded model

Claude Backend Issues

# Check if API key is set
echo $ANTHROPIC_API_KEY

# Set API key if missing
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# When running in Claude Code, the API key is provided automatically

Safety Validation Too Strict

# 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.