mcpField
S
shell-scripter

shell-scripter

github.com/wyattowalsh开发551 次安装9 周前更新
代码仓库

关于 shell-scripter

shell-scripter 是用于生成、审查、转换和检查 Shell 脚本的技能，也可生成 Makefile 与 justfile。它面向使用 bash、zsh、fish 或 POSIX sh 的开发者，通过模式分析解释 ShellCheck 规则，但不会运行 ShellCheck。

主要功能

  1. 01根据自然语言生成 Shell 脚本
  2. 02引用 ShellCheck 规则审查脚本
  3. 03在 bash、zsh、fish 间转换
  4. 04按模式检查 POSIX 兼容性
  5. 05生成 Makefile 和 justfile

适用场景

  1. 01为描述的任务起草 Shell 脚本
  2. 02查找现有脚本中的常见问题
  3. 03将脚本转换为其他支持的方言
  4. 04检查脚本的 POSIX 兼容性

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wyattowalsh/agents --skill shell-scripter

安装后在 Claude Code 中输入/shell-scripter确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
convert-dialect.json
create-script.json
evals.json
implicit-trigger.json
negative-control.json
review-script.json
references/
common-pitfalls.md
dialect-differences.md
makefile-justfile.md
posix-compatibility.md
shellcheck-rules.md
scripts/
check.py
dialect-converter.py
script-analyzer.py
scripts/asset_toolkit/
__init__.py
_shared.py
common.py
package.py
validate_evals.py
validate_hooks.py
validate_skill.py

详细介绍

Shell Scripter

生成、审查、转换和 lint shell 脚本。生成 Makefile 和 justfile。提供 ShellCheck 规则 ID 的说明，但不会运行 ShellCheck。

**范围：**Shell 脚本（bash、zsh、fish、sh/POSIX）、Makefile、justfile。不适用于 Python 脚本（请使用 python-conventions）、CI/CD 流水线（请使用 devops-engineer），也不用于运行或测试脚本。

分派

$ARGUMENTS模式
create <description>根据自然语言生成 shell 脚本
review <script or path>检查常见问题并提供 ShellCheck 规则参考
convert <script or path> <target>转换方言（bash/zsh/fish）
posix <script or path>在模式层面检查 POSIX 兼容性
makefile <tasks>根据任务描述生成 Makefile
justfile <tasks>根据任务描述生成 justfile
关于 shell 脚本的自然语言根据意图自动检测模式
空显示包含示例的模式菜单
自动检测启发式规则
  1. 指向 .sh/.bash/.zsh/.fish 文件的路径 + 修改动词（review、check、fix、audit、lint） -> review
  2. 指向 .sh 文件的路径 + “to zsh/fish/bash” -> convert
  3. 指向 .sh 文件的路径 + “posix” 或 “portable” -> posix
  4. 输入中包含 “makefile” 或 “make targets” -> makefile
  5. 输入中包含 “justfile” 或 “just recipes” -> justfile
  6. 描述期望的脚本行为 -> create
  7. 意图不明确 -> 询问要使用哪种模式

模式：Create

根据自然语言描述生成 shell 脚本。

生成流程
  1. 确定目标方言（默认为 bash）
  2. 运行 uv run python scripts/dialect-converter.py --list-features <dialect>，确认可用功能
  3. 编写脚本，要求：
    • 使用正确的 shebang（例如基于 env 的 env bash，而非硬编码解释器路径）
    • bash 使用 set -euo pipefail（其他方言使用等效设置）
    • 变量名有意义，并对展开结果加引号
    • 处理外部命令的错误
    • 如果脚本接受参数，则提供用法函数
验证
  1. 对生成的脚本运行 uv run python scripts/script-analyzer.py --stdin <<< "$SCRIPT"
  2. 修复发现的问题，并展示最终脚本

模式：Review

检查 shell 脚本中的常见问题。提供 ShellCheck 规则 ID 参考。

分析
  1. 读取目标脚本
  2. 运行 uv run python scripts/script-analyzer.py <path>
  3. 解析 JSON 输出：{shebang, dialect, issues, posix_compatible, complexity_estimate}
  4. 对每个问题，加载 references/shellcheck-rules.md 以解释相应的规则 ID
发现报告
  1. 按严重程度分组：错误 > 警告 > 信息 > 风格
  2. 展示发现的问题，包含：
    • ShellCheck 规则 ID（例如 SC2086）
    • 行号和代码片段
    • 说明问题所在
    • 具体修复方法
  3. 如果没有发现问题，请明确说明

严重程度对应关系：

严重程度示例
错误条件表达式中的变量未加引号、语法错误、命令注入
警告缺少错误处理、通配符展开未加引号、已弃用的语法
信息不够理想的模式、不必要的子 shell、冗余命令
风格引号使用不一致、缺少 shellcheck 指令、命名问题

模式：Convert

在 bash、zsh 和 fish 之间转换 shell 语法。

  1. 读取源脚本
  2. 识别源方言（根据 shebang 或 --from 标志）
  3. 运行 uv run python scripts/dialect-converter.py <path> --from <source> --to <target>
  4. 解析 JSON 输出：{converted_script, changes, warnings}
  5. 展示转换后的脚本，并附上变更摘要表
  6. 标出在目标方言中没有直接等效写法的结构

模式：POSIX

在语法模式层面检查脚本是否符合 POSIX。

  1. 读取目标脚本
  2. 运行 uv run python scripts/script-analyzer.py <path> --posix
  3. 找出 bash-ism：[[ ]]、(( ))、数组、local、source、进程替换、{a..z}、$'...'
  4. 对每个 bash-ism，根据 references/posix-compatibility.md 提出 POSIX 等效写法
  5. 报告脚本是否兼容 POSIX，或列出所需修改

模式：Makefile

根据任务描述生成 Makefile。

  1. 从 $ARGUMENTS 解析任务描述
  2. 确定任务之间的依赖关系
  3. 生成 Makefile，其中包含：
    • 为非文件目标声明 .PHONY
    • .DEFAULT_GOAL
    • 使用自文档化模式（## 注释）的 help 目标
    • 一致的变量命名（UPPER_SNAKE_CASE）
    • 多行配方需要共享状态时使用 .ONESHELL
  4. 遵循 references/makefile-justfile.md 中的约定

模式：Justfile

根据任务描述生成 justfile。

  1. 从 $ARGUMENTS 解析任务描述
  2. 生成 justfile，其中包含：
    • 配方说明注释
    • 默认配方（位于首位或使用 default 别名）
    • 在适当情况下为参数设置默认值
    • 需要使用非默认 shell 时设置 set shell 指令
    • 引用了环境变量时设置 set dotenv-load
  3. 遵循 references/makefile-justfile.md 中的约定

规范词汇

全文统一使用以下术语：

术语定义
方言Shell 语言变体：bash、zsh、fish、sh（POSIX）
bash-ismPOSIX sh 中没有的语法或功能（例如数组、[[ ]]）
shebang指定解释器的 #! 行
SC 规则ShellCheck 规则 ID（例如 SC2086 = 未加引号的变量）
配方justfile 目标（不要称为“任务”或“规则”）
目标Makefile 目标（不要称为“任务”或“配方”）
可移植无需修改即可在 bash/zsh/sh 中运行

参考文件

每次只加载一个参考文件。不要预先将所有参考文件加载到上下文中。

文件内容读取时机
references/shellcheck-rules.md前 50 条 ShellCheck 规则，包括严重程度、说明、示例和修复方法审查模式、解释 SC 规则 ID 时
references/posix-compatibility.mdPOSIX 内置命令、bash-ism 及其 POSIX 等效写法、可移植性模式POSIX 模式、使用 --posix 的创建模式
references/dialect-differences.mdbash/zsh/fish 之间的语法差异及转换方法转换模式、跨方言问题
references/common-pitfalls.md未加引号的变量、缺少错误处理、注入、竞态条件、陷阱审查模式、创建模式的最佳实践
references/makefile-justfile.mdMakefile 最佳实践、justfile 语法和模式、迁移指南Makefile 模式、justfile 模式
脚本运行时机
scripts/script-analyzer.py审查和 POSIX 模式——对 Shell 脚本进行静态分析
scripts/dialect-converter.py转换模式——在不同方言之间转换语法

关键规则

  1. 绝不能声称运行了 ShellCheck——应引用 SC 规则 ID 并解释规则，但分析基于模式
  2. 始终使用基于 env 的 shebang（例如，env bash），绝不使用硬编码的解释器路径
  3. 生成的 bash 脚本默认使用 set -euo pipefail——只有在明确说明理由时才省略
  4. 始终为变量展开添加引号，除非有意进行分词（SC2086）
  5. 除非别无选择，否则绝不生成使用 eval 的脚本——并解释其风险
  6. 每个生成的脚本都必须包含对外部命令的错误处理
  7. 生成的 Makefile 必须包含 .PHONY 声明和 help 目标
  8. 生成的 justfile 必须有默认配方和文档注释
  9. 审查发现必须包含 SC 规则 ID、行号和具体修复方法
  10. 绝不修改正在审查的脚本——审查仅限只读
  11. 转换模式必须警告目标方言中没有直接等价项的结构
  12. POSIX 模式必须指出每一处 bash 特有语法，并提供 POSIX 替代方案

评论

支持 Markdown