ProjectAGiPrompt/1-AgentSkills/writing-bash-scripts/SKILL.md

name: writing-bash-scripts description: Generates production-grade Bash scripts with strict mode, modular structure, unified logging, error handling, and ShellCheck compliance. Triggered by requests like "write a bash script", "create shell script", "generate CLI tool in bash". Keywords: bash, shell, script, devops. argument-hint: "" allowed-tools: - Read - Write - Bash - Glob - Grep

Writing Production-Grade Bash Scripts

Purpose

Transform functional requirements into a single, deployable Bash script following engineering best practices.

Arguments

$ARGUMENTS = functional requirement description (目标、输入/输出、流程、约束、示例数据等)

If $ARGUMENTS is empty, prompt user for:

• Target functionality
• Input/output specification
• Constraints (OS, permissions, dependencies)

Dynamic Context

!echo "Current working directory: $(pwd)"

!bash --version | head -1

---

Plan Phase

Deliverables Checklist

• Single .sh file with shebang #!/usr/bin/env bash
• Bash >= 5.0 requirement documented
• ASCII call graph at script top
• usage/help function (-h/--help)
• Parameter parsing (getopts)
• Exit code documentation
• --dry-run support
• --verbose/--quiet support
• Cleanup trap for temp files

Decision Points

Decision	Default	Override Condition
POSIX vs Bash-specific	POSIX preferred	Use Bash features only when necessary (arrays, [[ ]], mapfile); comment reason
Destructive ops	Require --force	Never auto-delete without confirmation
Temp file location	mktemp -d	User-specified via --tmp-dir

---

Execute Phase

Script Structure (固定顺序)

1. Shebang + Metadata
2. ASCII Call Graph
3. Global Constants (readonly)
4. Strict Mode Setup
5. Dependency/Environment Checks
6. Logging & Error Handling Functions
7. Business Functions
8. main() + Entry Point
9. Self-test Examples (comments)

Strict Mode (必须)

set -Eeuo pipefail
IFS=$' \t\n'

Required Functions

Function	Purpose
usage	Print help with examples
die	die <msg> <exit_code> - unified error exit
log_debug/info/warn/error	Timestamped logging with LOG_LEVEL control
run_cmd	Command wrapper: dry-run, retry, error capture
cleanup	Remove temp files/locks on EXIT/ERR/INT/TERM

Function Documentation Format

### <one-line description>
### @param <name> <type> <purpose>
### @return <exit_code> <status>
### @require <dependency/permission>
### @side_effect <file/network/system impact>
function_name() {
    ...
}

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	Missing dependency
4	Permission denied
5	File/resource not found
126	Command not executable
127	Command not found

See reference/exit-codes.md for extended codes.

Logging Format

[YYYY-MM-DD HH:MM:SS] [LEVEL] message

---

Verify Phase

Pre-Delivery Checklist

Frontmatter & Structure

• Shebang is #!/usr/bin/env bash
• Bash version requirement stated
• ASCII call graph present
• Sections in correct order

Safety & Defaults

• set -Eeuo pipefail enabled
• All variables double-quoted (except intentional word splitting with comment)
• No unquoted $@ or $*
• No unsafe eval
• --dry-run implemented
• --force required for destructive ops
• mktemp used for temp files
• trap covers EXIT/ERR/INT/TERM

Functions

• Every function has ### doc block
• @param, @return, @require present
• snake_case naming
• Input validation on all external inputs

Logging & Errors

• log_* functions implemented
• LOG_LEVEL controls output
• die includes line number and function stack
• run_cmd wrapper used for external commands

Quality

• Passes ShellCheck (or disables with # shellcheck disable=SCxxxx + reason)
• 3+ self-test examples in comments (normal, error, dry-run)
• No hardcoded paths without override option

ShellCheck Validation

shellcheck -x -s bash <script.sh>

Use scripts/shellcheck-wrapper.sh for automated checking.

---

Common Pitfalls

Pitfall	Fix
Unquoted variables in paths with spaces	Always "$var"
Missing local in functions	Declare with local var=...
Assuming GNU tools on macOS	Check uname or use portable flags
Ignoring exit code of piped commands	set -o pipefail + check ${PIPESTATUS[@]}
Temp files left on error	Trap cleanup on ERR/EXIT

---

Reference Files

When	Read
Need detailed code structure	reference/code-structure.md
Writing function docs	reference/function-template.md
Defining custom exit codes	reference/exit-codes.md
Starting from scratch	examples/minimal-template.sh

---

Minimal Self-Test Commands

# 1. Help
./script.sh --help

# 2. Dry-run
./script.sh --dry-run <args>

# 3. Invalid argument (expect exit 2)
./script.sh --invalid-option

# 4. Verbose mode
./script.sh --verbose <args>