「検証を頼み忘れて、lint が通っていないまま『できました』と言われたことがあります」
「検証の手順をスキルにしたいのですが、どこまでをスキルに書いて、どこからを人の仕事にすればいいですか」
第5回までで、スキルを複数のファイルに分ける考え方、スクリプトを読まずに実行させる書き方、allowed-tools による事前承認を見ました。ここからは、それらを使って検証のスキルを作ります。
検証は、スキルにするのに向いた作業です。手順が毎回同じで、頼み忘れると困り、しかも途中で止まる所が決まっているからです。この連載では、Ansible の playbook・role を変更した後の検証を、ansible-verify というスキルにします。
検証スキルは、長くなるので前後編に分けます。前編の第6回では、検証の6段階のうちスキルに任せる範囲、フォルダーの構成、SKILL.md の案を扱います。verify.sh と reference/reading-diff.md の中身、CLAUDE.md を短くする方法、動かしたときの流れは、後編の第7回です。数値・仕様は2026年10月時点です。
題材：検証の6段階
Academy の講座「Claude Code in action」のレッスン3「Verification skills」（日本語版では「検証スキル」）は、最初に作るなら検証のスキルだと勧めています。確認を頼み忘れても、スキルが毎回同じ手順で確かめてくれるからです。日本語版のレッスンには、「同じ複数ステップの指示を2回タイプしたなら、それはスキルだ」という経験則も書かれています。
ここでは、それを Ansible の作業用に作ります。連載「Claude Code実践入門」第7回の「Ansibleでの検証の型」は、検証を6段階に分けていました。そのうち、Claude に任せてよい①〜③をスキルにします。
| 段階 | 内容 | 担当 | スキルに書くか |
|---|---|---|---|
| ① 静的検査 | ansible-lint | Claude | 書く |
| ② 構文確認 | ansible-playbook --syntax-check | Claude | 書く |
| ③ 差分確認 | stg に --check --diff | Claude | 書く（結果を見せたところで止まる） |
| ④ 差分を人が読む | changed の項目が計画どおりかを確かめる | 人 | 書かない |
| ⑤ 本実行 | 人が承認してから実行する | 人 | 書かない（本実行と prod は書かない） |
| ⑥ 結果の確認と記録 | 実行後の状態を確かめ、記録する | Claude と人が一緒に | スキルの範囲の外 |
- ①〜③はスキル、④⑤は人、⑥は両方
- スキルは、③の結果を見せて止まる
- 本実行と prod は、スキルに書かない。権限（ask）とフックで守る
スキルは、③の結果を見せたところで止まります。④差分を人が読む、⑤本実行（人が承認）は人の仕事で、⑥結果の確認と記録は Claude と人が一緒に行います。本実行と prod はスキルに書きません。
スキルは指示であって強制ではないからです。スキルに「本実行しない」と書いても、それは依頼であって、保証ではありません。本当に止めるのは、権限の ask（連載「Claude Code実践入門」第6回の「Ansibleの作業での設定例（筆者の例）」）と、フックです（連載「Claude Code実践入門」第4回の「CLAUDE.md・Skills・フックの役割分担」、第7回の「フックで止める」、連載「Claude Codeフック入門」第3回の「何を止めるか」、第4回の「すり抜けへの備え」）。
補足：指示の限界は、公式の文書も説明しています。CLAUDE.md やスキルの「編集しない」は依頼であって保証ではなく、止めるのはフックです（https://code.claude.com/docs/ja/features-overview ）。
フォルダーの構成（案）
ansible-verify のフォルダーは、第4回の「フォルダーの構成」で見た構成を使います。
- 置き場所：Ansible リポジトリの
.claude/skills/ansible-verify/。Git で共有する（第8回の「共有の手順」） SKILL.md：手順、止まるところ、報告の形。短く保つ（次の節）reference/reading-diff.md：changed の読み方、冪等性の見どころ、落とし穴（handler 名の変更など。連載「Claude Code実践入門」第4回の「書くこと・書かないこと」）。差分を確かめるときだけ読ませる（第7回の「reference/reading-diff.md（案）」）scripts/verify.sh：①〜③を順に実行し、結果を RESULT 行にまとめる。読まずに実行させる（第7回の「scripts/verify.sh（案）」）- 名前：
ansible-verify。verifyだけにしない（第3回の「似たスキルを分ける・名前を具体的に」、第8回の「優先順位と名前の付け方」） - 呼び方：
bash .claude/skills/ansible-verify/scripts/verify.sh inventory/stg/hosts.ini site.yml - 書かないもの：本実行と prod のコマンド、パスワード、ホスト名や IP アドレスの一覧（連載「Claude Code実践入門」第4回の「書くこと・書かないこと」の「よく変わる情報」）
名前を verify だけにしないのは、Claude Code に組み込みの /verify スキルがあるからです。公式のコマンド一覧には、/verify が「コードの変更が意図どおりかを、アプリをビルドして実行し、結果を観察して確かめる」組み込みのスキルとして載っています。同じ名前では紛らわしいので、ansible-verify と、何の検証かが分かる名前にします。名前の付け方は第3回の「似たスキルを分ける・名前を具体的に」、優先順位は第8回の「優先順位と名前の付け方」で扱います。
呼び方の例の inventory/stg/hosts.ini は、筆者の練習用リポジトリ（連載「Claude Code実践入門」の演習で作ったもの）の stg のインベントリです。
補足：筆者の例の補助フォルダーは reference/（単数）です。オープン標準の仕様の提案は references/（複数形）で、名前は SKILL.md からのリンクで決まります（第4回の「フォルダーの構成」）。この連載は reference/ にそろえます。
SKILL.md（案）
SKILL.md の案の要点は、次の4つです。
- description：第3回の「発動しない説明と発動する説明」の良い例と同じ文言（依頼の言い回し3つと、playbook を編集し終えたとき）
allowed-tools：verify.sh の呼び方だけを事前承認する。本文で実行させるコマンドと同じ書き方にそろえる- 本文の流れ：読まずに実行 → RESULT 行を確かめる（3回まで） → changed を計画と突き合わせる → 報告 → 止まる
- してはいけないこと：本実行（
--checkなし）、inventory/prodへの実行。必要なら、コマンドを示して人に頼む
---
name: ansible-verify
description: Ansible の playbook・role を変更した後の検証（ansible-lint、構文確認、stg への --check --diff）を行う。「検証して」「lint 通る？」「stg で差分を見て」と頼まれたとき、または playbook を編集し終えたときに使う。
allowed-tools: Bash(bash .claude/skills/ansible-verify/scripts/verify.sh *)
---
# Ansible の検証（lint・構文確認・差分確認）
1. 次のスクリプトを、中身を読まずに実行する：bash .claude/skills/ansible-verify/scripts/verify.sh inventory/stg/hosts.ini site.yml
2. 最後の RESULT 行に 0 以外があれば、原因を報告に書く。今回の変更が原因なら直して 1 へ（3回まで）。既存の指摘や unreachable は直さず報告する
RESULT skipped=prod は、何も実行していないという意味
3. changed の項目を計画と突き合わせる。読み方は reference/reading-diff.md（差分を確かめるときだけ読む）
4. 報告する：実行したコマンド、RESULT 行、changed の一覧、計画にない変更の有無
5. ここで止まる。差分を人が読む（④）と、本実行（⑤）は人の判断
してはいけないこと：本実行（--check なし）、inventory/prod への実行。必要ならコマンドを示して人に頼む補足：description は1行で書きます（画面では折り返して見えます）。allowed-tools は呼んだターンの間だけ有効で、組織の設定によっては無視されます（https://code.claude.com/docs/ja/skills ）。
案の読み方
- frontmatter の
name：フォルダー名と同じansible-verify。筆者の書き方です（公式の文書では、frontmatter の項目はすべて任意で、推奨されるのは description です） - description：何をするか（playbook・role を変更した後の検証。3つの検査）と、いつ使うか（「検証して」「lint 通る？」「stg で差分を見て」と頼まれたとき、または playbook を編集し終えたとき）の両方を書く。第3回の「普段の言い回しを入れる」の書き方と同じです
allowed-tools：Bash(bash .claude/skills/ansible-verify/scripts/verify.sh *)は、verify.sh の呼び方だけです。Bash全体やansible-playbook *のような広い書き方はしません（第5回の「allowed-tools で事前承認する」）。本文の手順1のコマンドと同じ書き方にそろえておきます。公式の文書は、Bash のルールは Claude が書いたコマンドの文字列に一致させるものと説明しています。allowed-toolsのパターンも同じ形のルールなので、公式の Skills のページにも、本文が実行させるコマンドとallowed-toolsのルールを同じ書き方にそろえると、そのコマンドが確認なしで動く、という例があります（${CLAUDE_SKILL_DIR}の例。第5回の「allowed-tools で事前承認する」）。前方一致かどうかなど、一致の細かい条件を直接書いた公式の文は、筆者は見つけられていません- 手順1：スクリプトを読まずに実行する（第5回の「スクリプトは読まずに実行させる」）。
bashを付けて呼びます - 手順2：最後の RESULT 行（①〜③の終了コードを1行にまとめたもの。第7回の「scripts/verify.sh（案）」）に0以外があれば、原因を報告に書きます。今回の変更が原因なら直してやり直す（3回まで）。既存の指摘や unreachable は、今回の作業の範囲の外なので直さず、報告します。
RESULT skipped=prodは、prod を含む inventory だったので、スクリプトが何も実行しなかった、という意味です - 手順3：changed の項目を、作業の前に立てた計画と突き合わせます。読み方は
reference/reading-diff.mdに分け、「差分を確かめるときだけ読む」と条件を付けます（第4回の「SKILL.md から「いつ読むか」を書く」） - 手順4・5：報告に、実行したコマンド、RESULT 行、changed の一覧、計画にない変更の有無を入れ、そこで止まります。④差分を人が読むのと、⑤本実行の承認は、人の判断です
- してはいけないこと：本実行と prod は書かず、必要ならコマンドを示して人に頼ませます。ただし、これは依頼であって強制ではないので、prod は権限の ask で、確認が必ず出るようにします
この案で、allowed-tools を書いたスキルは、呼ぶ時点で承認を求められることがあります（筆者の実測は、第5回の「筆者が試したら：allowed-tools はいつ効いたか」にあります）。確認の画面が出ても、スキルが悪いわけではありません。何の確認かを、画面の文言で見分けてください。
考えてみよう
- 検証の6段階のうち、スキルに書くのはどれで、書かないのはどれですか。書かない段階について、それぞれ理由を言ってみてください
- SKILL.md の案の
allowed-toolsをBashだけにすると、何が事前承認されますか。Bash(bash .claude/skills/ansible-verify/scripts/verify.sh *)に絞ると、何が違いますか - SKILL.md に「本実行しない」と書いてあっても、本実行を止める保証にはなりません。何を足せば、本実行や prod への実行を確実に止められますか
ヒント：1は「題材：検証の6段階」、2は第5回の「allowed-tools で事前承認する」と「案の読み方」、3は「題材：検証の6段階」の本文（スキルは指示であって強制ではない）を見直してください。
まとめ
- 検証は、スキルに向いた作業。①静的検査（ansible-lint）・②構文確認（
--syntax-check）・③差分確認（stg への--check --diff）をスキルにし、④差分を読む・⑤本実行は人、⑥結果の確認と記録は Claude と人が一緒に行う - スキルは、③の結果を見せて止まる。本実行と prod はスキルに書かない。スキルは指示であって強制ではないので、ask とフックで守る
- フォルダーは、
SKILL.md（手順・止まるところ・報告の形）、reference/reading-diff.md（差分を確かめるときだけ読む）、scripts/verify.sh（読まずに実行）。名前はansible-verify（組み込みの/verifyと区別する） - SKILL.md の案は、description、
allowed-tools（verify.sh の呼び方だけ）、本文の流れ（読まずに実行 → RESULT 行を確かめる → changed を計画と突き合わせる → 報告 → 止まる）、してはいけないこと allowed-toolsは、本文で実行させるコマンドと同じ書き方にそろえる
次回は、後編として、verify.sh の案（終了コードの取り方、RESULT 行、prod をスクリプト自身で止める）、reference/reading-diff.md の案、CLAUDE.md を短くする方法、動かしたときの流れを扱います。
連載「Claude Codeスキル入門」全12回
全回の目次と、読む順番・目的別の読み方は、Claude Codeスキル入門の入口のページにまとめています。
- スキルとは何か
- SKILL.mdを書く
- 発動する説明を書く
- 複数のファイルに分ける
- スクリプトとallowed-tools
- 検証スキルを作る（前編）（この記事）
- 検証スキルを作る（後編）
- Gitでチームに共有する
- うまく動かないとき
- 演習（前編）：作る・確かめる・発動させる
- 演習（中編）：分ける・事前承認
- 演習（後編）：共有と振り返り
コメント