shellcheck-configuration

shellcheck-configuration スキルの概要

shellcheck-configuration スキルでできること

shellcheck-configuration スキルは、実運用レベルでシェルスクリプト品質を改善するために、ShellCheck の導入・解釈・チューニングをエージェントが進めるのを支援します。単に「linter を実行する」だけでは足りず、プロジェクト単位の設定、CI での判定基準、対象シェルの選定、警告抑制の方針、移植性を壊さずに指摘へ対応する進め方まで必要な場面で特に有効です。

shellcheck-configuration を使うべき人

このスキルが向いているのは、次のようなケースです。

• リポジトリに初めて ShellCheck を導入する開発者
• CI やコードレビューでシェル lint の基準を統一したいチーム
• 既存の bash、sh、dash、ksh スクリプトを整理したいメンテナー
• 場当たり的なコメントではなく、一貫した lint 方針でレビューしたいレビュアー

主な目的が「1 つの warning code の意味を知りたい」程度であれば、通常のプロンプトでも十分なことがあります。逆に、再現性のある設定や運用ポリシーまで固めたいなら、shellcheck-configuration skill のほうが適しています。

実際に解決したい仕事

ユーザーが最終的に求めている成果は、たいてい次の 4 つのいずれかです。

1. 利用中のプラットフォームで ShellCheck を正しくインストールする
2. 対象シェルと許容するルール水準に合わせて設定する
3. CI やマージ前チェックに組み込む
4. ノイズの多い lint 出力を、修正可能な課題とレビュー基準に落とし込む

このスキルは、ツールの使い方だけでなく、運用判断まで含めて整理したいときに最も力を発揮します。

一般的なプロンプトと何が違うのか

一般的なプロンプトでも「ShellCheck を使うとよい」と勧めることはできます。ですが shellcheck-configuration スキルは、次のような構造化された支援が必要なときにより実用的です。

• 対象シェルを選び、それに合うオプションを決める
• 何を suppress し、何を厳格に守るか判断する
• リポジトリに合った .shellcheckrc ポリシーを作る
• false positive を保守しやすい形で扱う
• ローカル実行用 lint だけでなく、Code Review に ShellCheck を活用する

導入時に理解しておきたい制約

このスキルは、自動化中心というよりガイド重視です。リポジトリ上の根拠を見る限り、存在するのは単一の SKILL.md で、補助スクリプトやパッケージ済みリソースはありません。つまり、リポジトリにそのまま適用できる完成済みコマンド群よりも、強い指針と具体例が得られるタイプです。実際のシェルファイル、現在のエラー、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 パイプラインへ組み込みたい
• シェル変更を含む pull request をレビューしたい
• inline disable を許容してよいケースか判断したい

スキルがうまく機能するために必要な入力

「ShellCheck を設定して」だけではなく、具体的な材料を渡してください。特に有効なのは次の情報です。

• 対象シェル: bash、sh、dash、ksh
• サンプルスクリプト、またはリポジトリのパス
• 現在の shellcheck 出力
• CI、コンテナ、複数ディストリでコードが動くかどうか
• チーム方針: warnings で fail するか、errors のみか、助言のみか
• 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.”

この依頼がうまく機能する理由は、次の条件が明確だからです。

• シェル構成が示されている
• どこまで厳格にするかが定義されている
• 実行環境の制約がわかる
• 単なるファイル出力ではなく、理由の説明まで求めている

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.

単に「このスクリプトをレビューして」と頼むより、論点の分類とポリシー適用を求めているぶん、結果の精度が上がりやすくなります。

インストールから運用強制までの推奨フロー

1. ShellCheck をインストールする
2. 対象シェルとリポジトリの目的を伝えて shellcheck-configuration スキルを呼び出す
3. .shellcheckrc を生成、または改善する
4. まずは代表的なスクリプトに対して shellcheck を実行する
5. CI で強制する前に、シグナルの強い warning を優先的に直す
6. 正当な例外に対する suppression ポリシーを決める
7. warning の量が管理可能になってから CI や pre-commit に組み込む

この順番にすると、方針が定まる前に lint gate だけ有効化してしまう、よくある失敗を避けやすくなります。

既存の lint 出力と一緒に shellcheck-configuration を使う方法

すでに shellcheck を実行済みなら、次の情報をそのまま貼り付けると有効です。

• SC2086、SC2046、SC2155 のような warning code
• 該当行
• 意図的な実装かどうか
• スクリプトの shebang で宣言されているシェル

特に役立つのは、その warning が次のどれに当たるかを見極めたい場面です。

• 実際のバグ
• 移植性リスク
• スタイル上の好み
• suppress する価値がある false positive

重要度の高い設定判断

影響が大きいのは、たいてい次の判断です。

• 対象シェルを正しく定めること
• プロジェクト単位の .shellcheckrc を使うかどうか
• グローバル ignore ではなく inline disable を優先すべき場面
• CI を全指摘で fail させるか、一部だけにするか
• 既存の legacy code をどこまで既得扱いにするか

ツールへの信頼感を左右するのは、個別 warning の修正よりも、こうした運用判断であることが多いです。

出力品質を上げる実践的なコツ

スキルには、次の成果物を明示的に作らせるのがおすすめです。

• .shellcheckrc のたたき台
• 具体例付きの suppression ポリシー
• CI コマンド例
• warnings の「今直す / 後で直す」トリアージ
• 繰り返し出る指摘に対するコードレビュー指針

生の ShellCheck 理論を求めるより、こうした形に落としてもらうほうが実務では役立ちます。このスキルには基礎知識もありますが、本当の価値はそれをリポジトリのポリシーに変換できる点にあります。

shellcheck-configuration スキル FAQ

shellcheck-configuration は初心者にも向いていますか？

はい。実際にシェルスクリプトを扱っている初心者であれば有用です。このスキルには ShellCheck の基礎やインストール案内も含まれているため、導入の足がかりになります。ただし、実際のスクリプトや現実の warning と組み合わせたときに、価値はより大きくなります。

ShellCheck をすでに知っていても shellcheck-configuration は必要ですか？

場合によります。warning 一覧やコマンドラインの基本を把握していても、リポジトリ全体の設定、CI ポリシー、suppression 戦略、ShellCheck を軸にしたレビュー運用の整理には依然として役立ちます。

自動化スクリプトやそのまま使える CI テンプレートは含まれていますか？

このスキルには、その強い根拠はありません。リポジトリ上のシグナルでは SKILL.md しか確認できないため、同梱スクリプトや再利用可能なテンプレートというより、考え方のガイドと例示が中心だと見てください。

shellcheck-configuration を使わないほうがよいのはどんなときですか？

次のような場合は、無理に使う必要はありません。

• shellcheck file.sh を 1 回だけ実行したい
• 問題の本質が静的解析ポリシーと無関係
• auto-fixer を求めている。ShellCheck は主に問題を報告するツールであり、コードを書き換えるものではない
• チーム内で設定方針がすでに固まっていて、必要なのがコマンド参照だけ

普通のプロンプトと shellcheck-configuration はどう違いますか？

通常のプロンプトでも warning の説明はできますが、リポジトリ単位の意思決定、つまり対象シェル、suppression の境界、導入手順、コードレビュー基準までは抜け落ちがちです。shellcheck-configuration guide は、その場限りの回答ではなく、繰り返し使える lint 運用を作りたいときに向いています。

shellcheck-configuration は複数シェル混在のリポジトリでも使えますか？

はい。ただし、混在状況を明示した場合に限ります。bash と POSIX sh が同居するリポジトリでは、適用範囲をはっきり伝える必要があります。そこが曖昧だと、一方のシェルには合うが、もう一方にはノイズになる提案が出やすくなります。

shellcheck-configuration スキルを改善する方法

実際のシェル実行環境を shellcheck-configuration に伝える

shellcheck-configuration の結果を最も手早く改善する方法は、次の情報を明示することです。

• スクリプト群ごとのシェル方言
• OS や CI runner
• スクリプトが source されるのか、直接実行されるのか
• 移植性が必要かどうか

ShellCheck の推奨内容は、シェルの意味論に大きく左右されます。前提が曖昧だと、助言も広すぎるものになりがちです。

要約ではなく実ファイルを渡す

「いくつか shell script がある」とだけ言うのではなく、次のような実物を渡してください。

• 代表的なスクリプト 1 本
• 既存の .shellcheckrc（あれば）
• 現在出ている warning code を数件
• 今の lint 実行に使っている CI スニペット

これにより、一般的なベストプラクティスから一歩進んで、実際の設定に踏み込んだ提案が可能になります。

構文だけでなくポリシーを求める

より良い依頼は次のようなものです。

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

弱い依頼は次のようなものです。

• “show shellcheck config options”

利用者が本当に知りたいのは、フラグの暗記よりも、何を標準化すべきかです。保守しやすいポリシーを選ぶ支援を、スキルに求めるのが効果的です。

よくある失敗パターンに注意する

出力がいまひとつになりやすい典型例は、次のとおりです。

• bash と sh の区別を指定していない
• warning だらけの legacy repo に、いきなり zero-warning 運用を求める
• 意味を理解する前に warning をグローバル suppress する
• すべての指摘を同じ重さで扱う
• コードレビューの流れを無視して、ローカル実行だけに話を限定する

このスキルは、単に列挙するためではなく、優先順位をつけるために使うと最も効果的です。

Code Review ワークフロー向けに shellcheck-configuration を改善する

レビュー用途では、指摘を次のカテゴリに分けるよう依頼してください。

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

こうすると、危険なシェルパターンは見逃さずに、価値の低いスタイル論でマージを止める事態を減らせます。

最初の出力のあとで反復する

最初の回答を受けたあと、次のように追加で依頼すると精度が上がります。

• “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?”

初回は方向性を定める段階、2 回目以降で運用基準を絞り込む、という使い方が適しています。

shellcheck-configuration を段階導入に使う

大きな legacy repo では、次の 3 段階を依頼するのが効果的です。

1. advisory ベースの初期設定
2. 優先度付きの修正リスト
3. 将来目標としての、より厳しい設定

最初から hard-fail linting を有効にして広い反発を招くより、この段階導入のほうがうまく進むことが少なくありません。

実際の ShellCheck 出力と照合して提案を検証する

最も確実な検証ループはシンプルです。

1. スキルに設定とポリシーを作らせる
2. shellcheck を実行する
3. 出てきた warning の傾向を確認する
4. その結果を再度スキルに渡して改善する

このループを回すことで、shellcheck-configuration skill は静的な解説ではなく、実際の導入と定着に使えるツールになります。