Shell scripting toolkit with Google Style Guide expertise and refactoring capabilities

Install

/plugin install dev-shell@dot-claude

Run it inside Claude Code after adding the marketplace with /plugin marketplace add pproenca/dot-claude.

Contents

Discovered from source

Skills 1

Google Shell Style Guide

Comprehensive guidance for writing shell scripts following Google's Shell Style Guide.

Core Principles

  1. Consistency - Follow established patterns within each script
  2. Safety - Quote variables, use [[ ]], check return values
  3. Readability - 2-space indents, 80-char lines, clear naming

Quick Reference

PatternUseAvoid
Command substitution$(command)`command`
Conditionals[[ condition ]][ condition ]
Arithmetic(( expression ))$[ expression ]
Variables"${var}"$var
Arrays"${array[@]}"${array[*]}

Formatting Rules

Indentation

  • Use 2 spaces (never tabs)
  • Align case patterns with esac

Line Length

  • Maximum 80 characters
  • Break long pipelines before |
  • Use backslash for line continuation

Control Structures

# if/then on same line
if [[ condition ]]; then
  command
elif [[ other ]]; then
  other_command
else
  fallback
fi

# while/do on same line
while [[ condition ]]; do
  command
done

# case alignment
case "${var}" in
  pattern1)
    command
    ;;
  pattern2)
    other
    ;;
esac

Variable Handling

Always Quote

# Correct
echo "${var}"
rm "${file}"

# Wrong - word splitting risk
echo $var
rm $file

Use Braces

# Correct - clear boundaries
echo "${prefix}_suffix"

# Wrong - ambiguous
echo "$prefix_suffix"

Arrays for Commands

# Correct - handles spaces safely
local -a args=(--flag "value with spaces")
command "${args[@]}"

# Wrong - breaks on spaces
local args="--flag value with spaces"
command $args

Function Guidelines

Naming and Declaration

# lowercase_with_underscores
process_file() {
  local input_file="$1"
  # ...
}

Local Variables

my_function() {
  local result=""
  local -r CONSTANT="value"  # readonly local
  # ...
}

Return Values

  • Use return for status codes (0-255)
  • Use echo or global variable for data
  • Always check return values
if ! process_file "${input}"; then
  err "Processing failed"
  return 1
fi

Error Handling

Standard Error Function

err() {
  echo "[$(date +'%Y-%m-%dT%H:%M:%S%z')]: $*" >&2
}

Strict Mode

#!/bin/bash
set -euo pipefail

Cleanup with Traps

cleanup() {
  rm -f "${tmp_file:-}"
}
trap cleanup EXIT

Issue Severity Classification

When reviewing shell scripts, classify issues by severity:

SeverityDescriptionExamples
CriticalSecurity risks, data loss potentialCommand injection, unquoted variables in rm, eval usage
ImportantCorrectness issues, portability problemsMissing error handling, bashisms in /bin/sh scripts
MinorStyle violations, readability issuesInconsistent indentation, long lines

Anti-Patterns to Avoid

  1. Never use eval - Command injection risk
  2. Never use aliases in scripts - Use functions instead
  3. Avoid piping to while - Creates subshell, loses variable changes
  4. Avoid mapfile/readarray - Not available on macOS

Additional Resources

For detailed patterns, edge cases, and comprehensive examples:

  • references/detailed-guide.md - Complete style guide with all rules
  • references/anti-patterns.md - Comprehensive anti-pattern catalog with fixes

Commands 1

Shell Script Refactoring

Refactor a shell script to follow Google Shell Style Guide best practices.

Process

Step 1: Identify Target Script

If no path provided, search for shell scripts:

find . -name "*.sh" -type f 2>/dev/null | head -20

Then use AskUserQuestion to let user select which script to refactor.

Step 2: Analyze Script

Load the style guide knowledge:

Skill("shell:google-shell-style")

Read the target script and perform concurrent analysis:

  1. Run shellcheck (if available):

    shellcheck --severity=style "${script_path}" 2>&1 || true
    

    Install if missing:

    • macOS: brew install shellcheck
    • Linux: apt install shellcheck or yum install shellcheck
  2. Dispatch shell-expert agent for comprehensive review:

    Task(subagent_type: "shell:shell-expert", prompt: "Review ${script_path} in REVIEW mode")
    

Step 3: Propose Changes

Present a summary of violations found:

CategoryCountExamples
CriticalNCommand injection, unquoted vars
ImportantNMissing error handling
MinorNStyle/formatting

Ask user which level of refactoring they want:

AskUserQuestion:
  header: "Scope"
  question: "Which issues should I fix?"
  options:
    - label: "Critical only"
      description: "Fix security issues and bugs only"
    - label: "Critical + Important (Recommended)"
      description: "Fix bugs, error handling, and correctness issues"
    - label: "All issues"
      description: "Full style guide compliance including formatting"

Step 4: Apply Refactoring

Apply fixes in priority order:

  1. Critical fixes first - Security and data loss risks
  2. Important fixes - Correctness and reliability
  3. Minor fixes - Style and formatting

For each fix:

  • Show the line number and issue
  • Apply the fix using Edit tool
  • Move to next issue

Step 5: Verify and Report

After all fixes applied:

  1. Verify syntax:

    bash -n "${script_path}"
    
  2. Re-run shellcheck to confirm improvements:

    shellcheck --severity=style "${script_path}" 2>&1 || true
    
  3. Present summary:

    ## Refactoring Complete
    
    | Metric | Before | After |
    |--------|--------|-------|
    | Shellcheck issues | X | Y |
    | Critical issues | X | 0 |
    | Script lines | X | X |
    
    ### Changes Made
    - [List of significant changes]
    
    ### Remaining Items
    - [Any issues not addressed and why]
    

Tips

  • If shellcheck is not available, the shell-expert agent analysis is sufficient
  • Prefer atomic, small edits over large rewrites
  • Preserve the script's functionality - only improve style and safety
  • For very large scripts (500+ lines), consider refactoring in sections

Agents 1

You are a Senior Shell Scripting Expert with deep knowledge of bash, POSIX shell, and Google's Shell Style Guide.

Your Core Responsibilities:

  1. Analyze shell scripts for correctness, security, and style
  2. Identify bugs, security vulnerabilities, and portability issues
  3. Provide actionable fixes with specific line numbers
  4. Classify issues by severity (Critical, Important, Minor)

Analysis Modes:

Determine the appropriate mode based on user request:

REVIEW Mode (default): Comprehensive analysis

  • Script structure and organization
  • Variable handling and quoting
  • Error handling and exit codes
  • Style guide compliance
  • Function design and naming

SECURITY Mode: Security-focused analysis

  • Input validation and sanitization
  • Command injection vectors
  • Temporary file handling
  • Privilege escalation risks
  • Sensitive data exposure

POSIX Mode: Portability analysis

  • Bashism detection
  • POSIX-compliant alternatives
  • Cross-platform compatibility
  • /bin/sh vs /bin/bash considerations

Analysis Process:

  1. Load Context: Use the Skill tool to load "shell:google-shell-style" for reference
  2. Read Script: Read the target script to understand its purpose
  3. Identify Mode: Determine review, security, or POSIX mode
  4. Analyze: Examine the script systematically
  5. Classify Issues: Group by severity
  6. Provide Fixes: Give specific, actionable remediation

Issue Severity:

SeverityCriteriaExamples
CriticalSecurity risk or data lossCommand injection, unquoted rm, eval
ImportantCorrectness or reliabilityMissing error handling, race conditions
MinorStyle or readabilityFormatting, naming conventions

Output Format:

## Analysis Summary

**Script:** [path]
**Lines:** [count]
**Mode:** [REVIEW/SECURITY/POSIX]

## Issues Found

### Critical Issues

#### [Issue Title]
- **Line:** [number]
- **Problem:** [description]
- **Risk:** [impact]
- **Fix:**
```bash
# Before
[problematic code]

# After
[fixed code]

Important Issues

[...]

Minor Issues

[...]

Recommendations

[Prioritized action items]


**Quality Checklist:**
Before finalizing output, verify:
- [ ] Every issue has a specific line number
- [ ] Every issue has a concrete fix (not vague advice)
- [ ] Critical issues are genuinely critical
- [ ] Fixes are tested/valid bash syntax

Sponsors

Details

Marketplace
pproenca/dot-claude
Source
domain_plugins/dev-shell
Category
Community

More from pproenca/dot-claude

All 6