shellcheck-configuration

shellcheck-configuration 技能總覽

shellcheck-configuration 技能的作用

shellcheck-configuration 技能可協助代理為真正的 shell script 品質工作設定、解讀並微調 ShellCheck。當你的需求不只是「跑一下 linter」時，它特別有用：像是專案層級設定、CI 擋關策略、目標 shell 選擇、warning 抑制策略，以及在不破壞可攜性的前提下修正問題的建議。

哪些人適合使用 shellcheck-configuration

這個技能特別適合：

• 第一次在 repository 中導入 ShellCheck 的開發者
• 想在 CI 或 code review 中統一 shell lint 規範的團隊
• 正在整理舊有 bash、sh、dash 或 ksh 腳本的維護者
• 希望用一致 lint 規則取代零散評論的 reviewer

如果你的主要需求只是「解釋某一個 warning code」，一般 prompt 可能就夠了。若你需要可重複執行的設定方式與團隊政策，shellcheck-configuration skill 會更適合。

真正要解決的工作需求

使用者通常想達成以下四種結果之一：

1. 在自己的平台上正確安裝 ShellCheck
2. 針對正確的 shell 與規則容忍度完成設定
3. 整合到 CI 或 merge 前檢查流程
4. 把雜訊很多的 lint 輸出整理成可執行的修正項目與 review 標準

當你的目標同時包含工具導入與決策制定時，這個技能最能發揮價值。

shellcheck-configuration 與一般 prompt 的差異

一般 prompt 可以建議你「使用 ShellCheck」。但當你需要以下這些有結構的協助時，shellcheck-configuration 技能會更實用：

• 選擇目標 shell，並搭配對應選項
• 決定哪些問題要 suppress、哪些必須強制執行
• 建立符合 repository 現況的 .shellcheckrc 政策
• 以可維護的方式處理 false positive
• 把 ShellCheck 用在 Code Review，而不只是本機 lint

導入前的重要限制

這個技能偏重指引，而不是自動化。從 repository 內容來看，只有單一 SKILL.md，沒有 helper script 或打包好的資源，所以你應該期待的是清楚的說明與範例，而不是可直接套用到你 repository 的現成指令。若你能提供實際 shell 檔案、目前錯誤以及 CI 情境，效果會最好。

如何使用 shellcheck-configuration 技能

shellcheck-configuration install 的安裝情境

先用以下指令把技能安裝到你的 agent 環境：

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 binary 本身。

先讀這個檔案

請從這裡開始：

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

由於這個技能沒有獨立的 README.md、規則檔或 helper script，幾乎所有實務建議都集中在這個檔案裡。在你根據整個 repo 去推測能力之前，應先把它讀完。

shellcheck-configuration 的最佳實際使用情境

當你有以下需求時，特別適合使用 shellcheck-configuration usage：

• 建立或調整專案的 .shellcheckrc
• 在嚴格執行與漸進式導入之間做取捨
• 修正大量腳本中反覆出現的 warning 模式
• 把 ShellCheck 接進 CI/CD pipeline
• review 含有 shell 變更的 pull request
• 判斷某個 inline disable 是否合理

讓技能發揮效果所需的輸入

請提供具體資訊，不要只說「幫我設定 ShellCheck」。理想輸入包括：

• 目標 shell：bash、sh、dash、ksh
• 範例腳本或 repository 路徑
• 目前的 shellcheck 輸出
• 程式碼是否跑在 CI、containers 或多種 distro
• 團隊政策：warning 就 fail、只有 error 才 fail，或僅提供建議
• 是否重視 POSIX sh 可攜性

若缺少這些背景，技能最多只能提供較通用的建議。

把模糊目標改寫成高品質 prompt

弱 prompt：

• 「Help me use ShellCheck.」

強 prompt：

• 「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 範例 prompt

你可以使用像這樣的 prompt：

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 與 repository 目標，呼叫 shellcheck-configuration 技能。
3. 產生或調整 .shellcheckrc。
4. 先對具代表性的腳本執行 shellcheck。
5. 在 CI 強制執行前，先修正高訊號的 warning。
6. 為合理例外制定 suppress 政策。
7. 等 warning 數量降到可控後，再加入 CI 或 pre-commit 整合。

這套順序能降低常見失敗情境：團隊還沒對政策取得共識，就先把 lint gate 打開。

如何搭配既有 lint 輸出使用這個技能

如果你已經跑過 shellcheck，請貼上：

• SC2086、SC2046、SC2155 這類 warning code
• 受影響的程式碼行
• 問題是否為刻意設計
• 腳本 shebang 宣告的 shell

當你想判斷某個 warning 屬於以下哪一種時，這個技能特別有價值：

• 真正的 bug
• 可攜性風險
• 風格偏好
• 值得 suppress 的 false positive

最重要的設定決策

影響最大的通常是以下幾項：

• 目標 shell 是否設定正確
• 是否採用專案層級的 .shellcheckrc
• 什麼時候該用 inline disable，而不是全域 ignore
• CI 應該對所有 findings fail，還是只擋其中一部分
• 舊有程式碼要保留多少既有例外

這些決策比修單一 warning 更影響大家對工具的信任度。

能提升輸出品質的實務建議

你可以要求技能產出：

• .shellcheckrc 草案
• 含範例的 suppress 政策
• CI 指令範例
• warning 的「現在先修 vs 之後再處理」分級
• 面對重複 findings 時的 code review 指引

這會比單純要求 ShellCheck 理論更有幫助。這個技能確實包含基礎知識，但真正價值在於把那些內容轉成適用於 repository 的實際政策。

shellcheck-configuration 技能 FAQ

shellcheck-configuration 適合初學者嗎？

適合，前提是你真的正在處理 shell script。這個技能包含 ShellCheck 基礎與安裝指引，因此能幫助初學者起步。不過它在搭配真實腳本與真實 warning 時，價值仍然最高。

如果我已經懂 ShellCheck，還需要 shellcheck-configuration 技能嗎？

有可能需要。即使你已經熟悉 warning 清單與 command-line 基本操作，這個技能對 repository 層級設定、CI 政策、suppress 策略，以及以 ShellCheck 為核心的 review workflow 仍然很有幫助。

它有包含自動化 script 或現成 CI template 嗎？

這個技能沒有明確證據顯示有提供。從 repository 訊號來看只有 SKILL.md，所以應預期它提供的是觀念性指引與範例，而不是內建 script 或可重用 template。

什麼情況下不該使用 shellcheck-configuration？

以下情況可以略過：

• 你只需要跑一次 shellcheck file.sh
• 你的問題與靜態分析政策無關
• 你想要 auto-fixer；ShellCheck 主要是回報問題，而不是重寫程式碼
• 你的團隊已經確定好設定，只需要查指令用法

這和一般 prompt 有什麼不同？

一般 prompt 可以解釋 warning，但常常會漏掉 repository 層級的決策：目標 shell、suppress 邊界、導入策略，以及 code review 標準。當你要的是可重複執行的 linting 方法，而不是一次性的回答時，shellcheck-configuration guide 會更合適。

shellcheck-configuration 適合混合 shell 的 repository 嗎？

適合，但前提是你要把混合情況講清楚。同時包含 bash 與 POSIX sh 腳本的 repo，需要明確界定範圍；否則建議很可能偏向其中一種 shell，進而對另一種產生不必要雜訊。

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

提供你實際的 shell 執行環境給技能

想讓 shellcheck-configuration 更快產出有用結果，最有效的方式是明確說明：

• 每組腳本使用的 shell dialect
• OS 或 CI runner
• 腳本是被 source 進來，還是直接執行
• 是否需要可攜性

ShellCheck 的建議高度依賴 shell 語意。輸入模糊，就容易得到範圍過大的建議。

提供真實檔案，而不是摘要描述

與其說「我們有一些 shell scripts」，不如直接提供：

• 一個具代表性的腳本
• 目前的 .shellcheckrc（如果有）
• 幾個目前的 warning code
• 現在 CI 中執行 lint 的片段

這樣技能才能從通用 best practice，進一步變成具體可用的設定建議。

要求政策建議，不要只問語法

更強的提問方式是：

• 「draft a .shellcheckrc and explain what the team should enforce」

較弱的提問方式是：

• 「show shellcheck config options」

使用者真正關心的，通常不是背熟 flags，而是哪些規則值得標準化。請要求技能協助你選出可長期維護的政策。

留意常見失敗模式

容易導致輸出品質不佳的常見情況包括：

• 沒有說明是 bash 還是 sh
• 在 warning 很多的 legacy repo 上，一開始就要求零 warning 強制執行
• 在還沒理解 warning 前，就先全域 suppress
• 把所有 findings 視為同樣嚴重
• 忽略 code review workflow，只聚焦在本機執行

這個技能最有幫助的地方，在於協助你做優先順序判斷，而不只是列出問題。

改善用於 Code Review 工作流的 shellcheck-configuration

若是用於 review，請要求技能將 findings 分類為：

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

這能幫 reviewer 避免因低價值的 style 問題擋下 merge，同時仍能抓出危險的 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?」

第一輪的重點應該是先定方向；第二輪再把強制規則調整到適合你的情境。

用這個技能分階段導入

面對大型 legacy repo，你可以要求：

1. 一份 baseline advisory configuration
2. 一份依優先順序排列的修正清單
3. 一份更嚴格的未來目標設定

這種分階段方式，通常比一開始就直接開啟 hard-fail linting 更好，也比較不會引發大範圍的開發者反彈。

用實際 ShellCheck 輸出回頭驗證建議

最佳驗證迴圈其實很簡單：

1. 先請技能提供 config 與政策
2. 執行 shellcheck
3. 檢查實際產生的 warning 組成
4. 再把結果回饋給技能進一步調整

這個迴圈能把 shellcheck-configuration skill 從靜態指引，變成真正可落地的導入工具。