Agent Skillsのワークフローとフィードバックループの書き方

Skillの本文が長い手順書になると、Claudeは途中の確認を省いたり、出力の形を毎回変えたりします。Agent Skillsのベストプラクティスには、これを抑える書き方が4つあります。チェックリスト付きの手順、validatorを挟む検証ループ、出力テンプレートと例、条件で分かれる手順です。

この記事は、それぞれをSKILL.mdにどう書くかを、ベストプラクティスの例とClaude Codeでの置き方に分けて示します。命名や参照ファイルの分割はAgent Skillsの命名規則と段階的開示の領分です。ここでは本文の中身、つまり手順の組み方を扱います。

どの型をどの場面で使うか

先に全体を表にします。迷ったら、Claudeが何を間違えるかから逆引きします。

チェックリストで手順を区切る

複雑な作業は、順番のあるステップに分けて書きます。特に長い手順では、Claudeが自分の応答にコピーして、済んだ項目に印を付けられる進捗表を置きます。

コードを使わないSkillの例は、調査結果をまとめる手順です。ベストプラクティスの例では、本文の冒頭に次の進捗表を置きます。

## Research synthesis workflow
 
Copy this checklist and track your progress:
 
```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```

進捗表のあとに、**Step 1: Read all source documents** のような見出しを付けた各ステップの説明が続きます。要点は最後のステップです。「引用が不完全ならStep 3に戻る」と、戻り先まで書いています。

スクリプトを使うSkillでは、各ステップが実行コマンドになります。PDFフォームの記入手順では、フォームの解析、fields.json の編集、検証、記入、出力の確認という5段階です。検証と確認のステップに専用スクリプトが割り当てられていて、確認が失敗したらステップ2へ戻る指示が付きます。

この型には、重要な検証をClaudeが飛ばすのを防ぐ狙いがあります。進捗表はClaudeだけでなく、結果を見る人が今どこまで進んだかを追う手がかりにもなります。

検証してから進む — フィードバックループ

定番の型は、validatorを走らせ、エラーを直し、もう一度走らせる流れです。この繰り返しで出力の質が大きく上がります。

ここで大事なのは、validatorがスクリプトとは限らない点です。例は2つあります。

どちらも、本文に書く骨格は同じです。作る、検証する、失敗したら直して検証に戻る、通ったら次へ。文書編集の例では、検証の行を太字にして「Validate immediately」「Only proceed when validation passes」と強調しています。飛ばしてほしくない行は、強い言い方で固定します。

エラーメッセージが直し方を決める

スクリプトで検証するなら、メッセージの質が修正の速さを左右します。実装上のヒントは、検証スクリプトに詳しいメッセージを返させることです。

たとえば Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed という形です。足りない名前だけでなく、使える候補まで返すので、Claudeは推測せずに直せます。

一括・破壊的な変更は、計画ファイルを先に検証する

ベストプラクティスの後半に、検証ループの発展形があります。いきなり本体を書き換えず、まず計画を構造化ファイルで作り、それをスクリプトで検査してから実行する型です。

想定は、スプレッドシートの内容でPDFの50個のフォーム欄を更新する作業です。検証なしだと、存在しない欄を指す、値が衝突する、必須欄が抜けるといった事故が起きえます。そこで流れを次のように変えます。

利点は、早く誤りを見つけられること、機械で確かめられること、元を触らずに計画だけやり直せること、エラーが具体的な問題を指せることです。使いどころは、バッチ処理、破壊的な変更、検証ルールが複雑な作業、失敗が重い作業です。

Claude Codeに置く例 — スクリプトを同梱した検証ループ

ここまでの型を、Claude Codeのスキルとして組み立てます。次のSKILL.mdは、ここまでの型を組み合わせた架空の例です。CSVを整えて取り込む作業を想定しています。

---
name: csv-import
description: CSVを検証してから取り込む。CSVの取り込み、列の整形、インポート前の確認を頼まれたときに使う。
allowed-tools: Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/validate_csv.py *)
---
 
# CSV取り込み
 
進捗表をコピーして、終わった項目に印を付けること。
 
```
Import Progress:
- [ ] Step 1: 列名とデータ型を確認する
- [ ] Step 2: 変換計画plan.jsonを作る
- [ ] Step 3: plan.jsonを検証する
- [ ] Step 4: 取り込みを実行する
- [ ] Step 5: 件数を突き合わせる
```
 
**Step 3: plan.json を検証する**
 
実行: `python3 ${CLAUDE_SKILL_DIR}/scripts/validate_csv.py plan.json`
 
エラーが出たら、メッセージの候補列名を見て plan.json を直し、再実行する。
**検証が通るまで Step 4 に進まない。**

置き方の要点は3つあります。

1つ目は、${CLAUDE_SKILL_DIR} を本文と allowed-tools の両方に書くことです。Claude Codeはこの変数を、スキルのマークダウンと allowed-tools のBashルールの2か所で置換します。同じ変数を両方に使うと、ルールが本文の指示するコマンドと一致するので、同梱スクリプトを許可確認なしで実行できます。Claude Codeのスキル解説に出てくる型です。

2つ目は、検証コマンドの失敗を、スクリプト側の終了コードとメッセージで表すことです。本文には、失敗時に何をするかを書きます。スクリプトの中身を本文に貼る必要はありません。呼び出し方と戻り先だけを書けば足ります。

3つ目は、失敗時の戻り先を番号で書くことです。「Step 2に戻る」と書いてあれば、Claudeは計画ファイルを直す工程へ迷わず戻れます。「やり直す」だけでは、どこからか分かりません。

スキルの配置場所や allowed-tools を含むfrontmatterの全項目はClaude Code Skills完全ガイドにまとまっています。手順の外側で「テストが通るまで止めない」を強制するなら、agent hookでテストを検証させる方法が別の手段になります。

検証スクリプト自体の書き方

検証ループは、スクリプトが雑だと回りません。同梱スクリプトには3つの注意があります。

• エラーはスクリプトの中で処理する: ファイルが無いなら既定の内容で作る、権限が無いなら代替を使う、のように、失敗をClaudeへ丸投げしません。open(path).read() だけで落とす書き方は悪い例です
• 定数に理由を書く: TIMEOUT = 47 の理由が分からなければ、Claudeも適切な値を決められません。「HTTPリクエストは通常30秒以内に終わる」のように根拠をコメントに残します
• 実行か参照かを本文で明示する: 「analyze_form.py を実行してフィールドを抜き出す」なら実行、「抽出の仕組みは analyze_form.py を参照」なら読み物です。ほとんどの補助スクリプトは実行させるほうが信頼でき、効率も良くなります

実行させる補助スクリプトは、コードをコンテキストに載せずに済むので、トークンの節約にもなります。生成させたコードより毎回同じ結果になる点も利点です。本文には、各スクリプトの一行説明と呼び出し例、戻り値の形(OK か衝突の一覧か)だけを書きます。

検証スクリプトの出力は、人が読む報告ではなくClaudeが次の手を決める入力です。前の節で見た「使える候補まで返す」エラーメッセージと合わせて、ここまでが検証ループの実装です。

出力の形はテンプレートか例で固定する

出力形式を揃えたいときの型が2つあります。

テンプレートは厳密さを使い分ける

要件の強さに合わせて、テンプレートの書き方を変えます。

出力を別の処理が読むなら厳密に、人が読む報告なら目安にします。厳密な雛形を、読み手が柔軟さを求める場面に使うと、不要な節まで埋められてしまいます。

例は入力と出力の対で見せる

説明より例のほうが、求める文体と詳しさを伝えやすい場合があります。例はコミットメッセージで、入力の説明と出力の対を3組並べています。

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication
 
Add login endpoint and token validation middleware
```

3組の末尾に「型は type(scope): brief description、そのあとに詳細」と一文でまとめています。例だけを置いて読み取りを任せず、守らせたい規則を最後に言葉でも添える形です。

分岐は条件付きワークフローで書く

作成か編集かで手順が変わるような作業は、判断点を先頭に置いて、分岐先を見出しに分けます。

## Document modification workflow
 
1. Determine the modification type:
 
   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

この例では、新規作成はdocx-jsでゼロから組み立てて書き出し、編集は既存文書を展開してXMLを直し、変更のたびに検証して、終わったら再パックします。

手順が大きくなって分岐が増えたら、別ファイルに切り出し、今の作業に合うファイルだけを読ませる方法があります。切り出し方は命名と段階的開示の記事のパターン3と同じ発想です。

選択肢を並べすぎないことも、手順を書く側の注意点です。「pypdfでも、pdfplumberでも、PyMuPDFでも」と並べると、Claudeは迷います。既定を1つ決め、必要なときだけ別手段へ逃がします。例外は一行で足します。

時間で変わる記述はOld patternsに畳む

Skillは長く使われるので、日付で分岐する書き方は後で嘘になります。悪い例は「2025年8月より前は旧API、後は新API」と本文に書くことです。

旧手順は履歴として残しつつ、本文を散らかしません。もう1つ、用語は1つに決めます。「API endpoint」と「URL」と「path」を混ぜず、「field」と「box」を混ぜない、といった統一です。Claudeが指示を読み取りやすくなります。

書いたあとに確かめること

出荷前チェックリストには、この記事の範囲と対応する項目があります。手順に明確なステップがあること、品質が重要な作業にフィードバックループがあること、重要な操作に検証や確認のステップがあること。時間依存の情報がないか、あっても旧手順の節にあること。用語が統一されていること。例が抽象でなく具体的であること。

出荷前の確認も同じ一覧にあります。評価を最低3つ作ること、Haiku・Sonnet・Opusで試すこと、実際の使い方で試すことです。評価の作り方とモデル別の観点は、命名の記事の書く前に評価を作り、モデルごとに確かめるの節に整理しています。本文を500行以内に保つ目安もこの一覧にあり、手順が膨らんだら別ファイルへ移します。

まとめ

チェックリストは、手順の飛ばしを抑えます。フィードバックループは、壊れた出力が次の工程に流れるのを止めます。両者は組み合わせて使う型で、ステップの途中に検証の行を挟むと一つに収まります。

型を足す順番は、問題が出た箇所からで足ります。出力が壊れるなら検証ループ、一括更新が怖いなら計画ファイル、形が揃わないならテンプレートか例、といった具合です。検証役が参照文書でもスクリプトでも本文の骨格は変わらないので、まず STYLE_GUIDE.md 方式で始めて、必要になったらスクリプトへ置き換える進め方もできます。