shellcheck-configuration

shellcheck-configuration 技能概览

shellcheck-configuration 技能能做什么

shellcheck-configuration 技能用于帮助智能体为真实的 shell 脚本质量治理正确设置、解读并调优 ShellCheck。如果你的需求不只是“跑一下 linter”，而是涉及项目级配置、CI 卡口、目标 shell 选择、告警抑制策略，以及在不破坏可移植性的前提下修复问题的建议，它就特别有用。

谁适合使用 shellcheck-configuration

这个技能适合：

• 第一次在仓库中引入 ShellCheck 的开发者
• 想在 CI 或代码评审中统一 shell lint 规范的团队
• 正在清理遗留 bash、sh、dash 或 ksh 脚本的维护者
• 希望用一致的 lint 规则替代零散人工评论的 reviewer

如果你的主要需求只是“解释某一个 warning code”，普通提示词往往就够了。
如果你需要一套可复用的配置与治理策略，shellcheck-configuration skill 会更合适。

真正要解决的问题

用户通常希望达成以下四类结果之一：

1. 在自己的平台上正确安装 ShellCheck
2. 按正确的 shell 目标和规则容忍度完成配置
3. 集成到 CI 或合并前检查流程
4. 把嘈杂的 lint 输出转成可执行的修复方案和评审标准

当你的目标同时包含工具落地和决策判断时，这个技能的价值最大。

它和普通提示词有什么区别

普通提示词可以告诉你“用 ShellCheck”。但当你需要结构化帮助时，shellcheck-configuration 技能更有价值，尤其是在这些方面：

• 选择目标 shell，并匹配对应选项
• 决定哪些规则该抑制，哪些必须执行
• 制定符合仓库现状的 .shellcheckrc 策略
• 以可维护的方式处理 false positive
• 把 ShellCheck 用到 Code Review，而不只是本地 lint

采用前需要知道的限制

这个技能更偏“高质量指导”，而不是“自动化代劳”。从仓库证据来看，只有一个 SKILL.md，没有辅助脚本或打包资源，因此你应预期它提供的是强指导性说明和示例，而不是针对你仓库直接可用的一键命令。要拿到最佳结果，最好提供真实的 shell 文件、当前报错以及 CI 上下文。

如何使用 shellcheck-configuration 技能

shellcheck-configuration 的安装环境说明

先把技能安装到你的智能体环境中：

npx skills add https://github.com/wshobson/agents --skill shellcheck-configuration

然后确认执行分析的环境里已经安装了 ShellCheck 本体：

# macOS
brew install shellcheck

# Ubuntu/Debian
apt-get install shellcheck

# Verify
shellcheck --version

这个技能负责配置和使用指导，并不能替代 shellcheck 二进制本身。

先看这个文件

优先阅读：

• plugins/shell-scripting/skills/shellcheck-configuration/SKILL.md

因为这个技能没有单独的 README.md、规则文件或辅助脚本，几乎所有实操建议都集中在这里。不要先从整个仓库的其他内容猜它的能力范围，先把这个文件读完。

shellcheck-configuration 在实战中的最佳使用场景

在以下场景下使用 shellcheck-configuration usage 会最有效：

• 创建或完善项目级 .shellcheckrc
• 在“严格执行”和“渐进落地”之间做取舍
• 修复大量脚本中反复出现的 warning 模式
• 把 ShellCheck 接入 CI/CD 流水线
• 评审包含 shell 变更的 pull request
• 判断某个 inline disable 是否合理

想让技能发挥效果，需要提供哪些输入

请提供具体输入，而不是只说“帮我配置 ShellCheck”。较好的输入包括：

• 目标 shell：bash、sh、dash、ksh
• 示例脚本或仓库路径
• 当前的 shellcheck 输出
• 代码是否运行在 CI、容器或多种发行版环境
• 团队策略：warning 就失败、只有 error 才失败，还是仅作提示
• 是否要求兼容 POSIX sh

缺少这些上下文时，这个技能只能给出比较泛的建议。

如何把模糊需求变成高质量提示词

弱提示词：

• “Help me use ShellCheck.”

强提示词：

• “Use the shellcheck-configuration skill to propose a .shellcheckrc for a repo with mostly bash scripts, a few POSIX sh entrypoints, CI on Ubuntu, and a goal of blocking high-confidence issues while allowing justified inline suppressions. Explain each config choice and how it affects code review.”

为什么这种写法更有效：

• 明确了 shell 混用情况
• 定义了执行强度
• 给出了环境约束
• 要求说明决策理由，而不是只吐出一个配置文件

面向 Code Review 的 shellcheck-configuration 提示词示例

可以这样提问：

Use the shellcheck-configuration skill for Code Review. Review this shell script diff, identify the ShellCheck issues most likely to matter in production, separate correctness bugs from style issues, and recommend whether to fix, suppress, or ignore each one. Assume the repo standard is Bash in CI but portability matters for small utility scripts.

这会比“review this script”效果更好，因为它要求智能体先分类问题，再按策略做判断。

从安装到落地执行的推荐流程

1. 安装 ShellCheck。
2. 带着你的 shell 目标和仓库治理目标调用 shellcheck-configuration 技能。
3. 生成或完善 .shellcheckrc。
4. 先在有代表性的脚本上运行 shellcheck。
5. 在 CI 强制执行前，先修掉高信号告警。
6. 为有充分理由的例外情况制定 suppression policy。
7. 只有在告警量可控之后，再加入 CI 或 pre-commit 集成。

这样的顺序可以避开一种常见失败模式：团队在策略尚未对齐前，就先把 lint gate 打开。

已经有 lint 输出时，如何配合技能使用

如果你已经跑过 shellcheck，请直接贴出：

• SC2086、SC2046、SC2155 这类 warning code
• 受影响的代码行
• 该问题是否是有意为之
• 脚本 shebang 声明的 shell

当你需要判断某个 warning 究竟属于以下哪一类时，这个技能尤其有价值：

• 真实 bug
• 可移植性风险
• 风格偏好
• 值得抑制的 false positive

最关键的配置决策是什么

影响最大的通常是这些决策：

• 目标 shell 是否选对
• 是否使用项目级 .shellcheckrc
• 什么时候应优先用 inline disable，而不是全局 ignore
• CI 应该对所有发现失败，还是只针对部分问题失败
• 对遗留代码要保留多少“历史包袱豁免”

这些决定比修单条 warning 更影响团队对工具的信任度。

能显著提升输出质量的实用建议

可以要求这个技能产出：

• 一份 .shellcheckrc 草案
• 带示例的 suppression policy
• CI 命令示例
• “现在修 / 以后修”的 warning 分级清单
• 针对重复性问题的 code review 指南

这比单纯让它讲 ShellCheck 理论更有用。技能里当然包含基础知识，但真正的价值在于把这些内容落到仓库策略上。

shellcheck-configuration 技能 FAQ

shellcheck-configuration 适合新手吗？

适合，前提是你正在实际处理 shell 脚本。这个技能包含 ShellCheck 基础知识和安装指导，因此能帮助新手起步。不过，它在结合真实脚本和真实 warning 时价值更高。

如果我已经会用 ShellCheck，还需要 shellcheck-configuration 吗？

可能仍然需要。即使你已经熟悉 warning 目录和命令行基础，这个技能在仓库级配置、CI 策略、抑制策略，以及基于 ShellCheck 的评审流程上仍然很有用。

它包含自动化脚本或现成的 CI 模板吗？

从这个技能本身看，没有明显证据表明包含这些内容。仓库迹象显示只有 SKILL.md，因此应预期它提供的是概念性指导和示例，而不是随附脚本或可复用模板。

什么情况下不该使用 shellcheck-configuration？

以下情况可以跳过：

• 你只需要临时跑一次 shellcheck file.sh
• 你的问题和静态分析策略无关
• 你想找自动修复工具；ShellCheck 主要是报告问题，不是重写代码
• 团队已经完全确定好配置，现在只需要命令参考

它和普通提示词的区别到底在哪？

普通提示词可以解释 warning，但经常忽略仓库级决策：目标 shell、抑制边界、推广节奏，以及 code review 标准。
当你要的是一套可重复执行的 lint 方法，而不是一次性回答时，shellcheck-configuration guide 更合适。

shellcheck-configuration 适合混合 shell 仓库吗？

适合，但前提是你要把混用情况说清楚。一个仓库里如果同时有 bash 和 POSIX sh 脚本，就必须明确划分作用范围；否则建议很容易过度偏向某一种 shell，给另一类脚本制造噪音。

如何改进 shellcheck-configuration 技能的使用效果

把你的真实 shell 环境告诉技能

提升 shellcheck-configuration 输出质量最快的方法，就是明确说明：

• 每类脚本分别使用什么 shell dialect
• OS 或 CI runner 是什么
• 脚本是被 source 还是直接执行
• 是否要求可移植性

ShellCheck 的建议高度依赖 shell 语义。输入模糊，输出就容易变得过宽泛。

提供真实文件，不要只给概述

与其说“我们有一些 shell 脚本”，不如直接提供：

• 一个有代表性的脚本
• 当前的 .shellcheckrc（如果有）
• 几个现有 warning code
• 今天用于跑 lint 的 CI 片段

这样技能才能从泛泛的最佳实践，推进到具体可落地的配置建议。

不要只问语法，要问策略

更强的提问方式是：

• “draft a .shellcheckrc and explain what the team should enforce”

较弱的提问方式是：

• “show shellcheck config options”

用户真正关心的，通常不是记住多少 flags，而是团队到底应该统一什么标准。让技能帮你制定可维护的 policy，价值会更高。

注意这些常见失败模式

以下做法很容易导致输出质量不佳：

• 不说明是 bash 还是 sh
• 面对告警很多的遗留仓库，却要求零 warning 强制执行
• 还没理解 warning 含义就先全局 suppress
• 把所有发现都当成同等严重
• 只盯着本地运行，忽略 code review 工作流

这个技能最有帮助的地方，在于帮你做优先级判断，而不只是罗列问题。

如何把 shellcheck-configuration 用到 Code Review 工作流

在评审场景中，可以要求技能把发现分类为：

• correctness
• quoting and expansion safety
• portability
• maintainability
• style-only

这样 reviewer 就不必为了低价值的风格问题阻塞合并，同时仍能抓住危险的 shell 模式。

第一次输出后要继续迭代

拿到第一轮结果后，可以继续追问：

• “tighten this config for CI”
• “make this safer for POSIX portability”
• “reduce false positives for sourced helper files”
• “which suppressions should stay inline rather than in .shellcheckrc?”

第一轮的目标是确定方向；第二轮才是把执行策略调到合适力度。

用这个技能分阶段推进落地

对于大型遗留仓库，可以要求它给出：

1. 一份基线 advisory 配置
2. 一份按优先级排序的修复清单
3. 一份更严格的未来态配置

这种分阶段推进方式，往往比一上来就启用 hard-fail linting 更有效，也更不容易引发大面积开发者抵触。

用真实的 ShellCheck 输出校验建议

最佳验证闭环其实很简单：

1. 先让技能给出配置和策略
2. 运行 shellcheck
3. 检查实际产生的 warning 组合
4. 再把结果回灌给技能继续细化

这个闭环能把 shellcheck-configuration skill 从静态指导，变成真正可用于推广落地的实用工具。