結論から書く。Claude Code の skill を信用できる状態にするには、ファイルを読み返すだけでは足りなかった。別コンテキストでのレビュー、全工程の実行、機械チェック、読み込み後の内容確認まで行って、初めて設計と実装のずれが見えた。
対象は、記事執筆の手順を固定するために作った run-article-harness である。skill とは、.claude/skills/ に置き、条件が合うと読み込まれる手順書を指す。
作成時には命名と構造を機械的に決める規約に沿って設計し、別コンテキストの evaluator にも採点させて 88/100 で合格した。それでも、実際に動かした直後に欠陥が5件出た。5件とも、SKILL.md を読み返した段階では見つかっていない。
これは skill の作り方の話ではない。作ったものをどうやって信用できる状態にするかの記録である。
何を固定し、何を固定しなかったか
きっかけは記事1本目の運用結果だった。同じ依頼文を4つのモデルへ同一投入したところ、依頼文で指定した項目は4モデルすべてが守り、書き忘れた項目は4モデルすべてが落とした。
ブリーフで指定した項目 → 4/4 達成
ブリーフで書き忘れた項目 → 0/4 達成差がモデルの能力ではなく依頼文の精度から出ていたため、固定する対象を依頼文の側にした。
| 固定するもの（検査できる） | 固定しないもの（型になる） |
|---|---|
| 事実ソースの限定 | 見出しの構成と順番 |
| 読者が知らない前提の説明 | どこを厚く書くか |
| 文体の禁止語・字数 | 切り口、比喩、語り口 |
| 法令要件（PR表記の位置） | 洞察を足すかどうか |
| 評価基準の事前登録 | どのモデルを使うか |
構成を固定しなかった理由は2つ。1本目で価値が出たのが指定しなかった部分（ある草稿が足した洞察、別の草稿のタイトルの立て方）だったこと。もう1つは、Google が複数ドメイン間のテンプレート／コンテンツ複製を、内容の薄いアフィリエイトサイトの判定材料に挙げているためである。作成記録（NOTES.md）ではこれを「制約は床を上げる。型は天井を下げる」と整理している。
禁止語の検出も skill 本文には書かなかった。手元の適格性規約では、禁止語のように機械判定できる処理は CI や CLI へ置くことになっていたため、scripts/check.sh へ分離した。
skill … ブリーフ・投入・採点・統合（判断が要る）
script … 字数・禁止語・タイトル・見出し・PR表記（判断が要らない）この線引きが、あとで欠陥の発見条件そのものになる。 検査が本文と別ファイルとして独立していたから、両者の食い違いが表に出た。
evaluator では合格していた
自己採点は同じ文脈のままだと甘くなる。そのため別コンテキストの evaluator へ渡した。
88 / 100（合格基準 80）
| 評価軸 | 点数 |
|---|---|
| axis_consistency | 92 |
| prefix_derivation_compliance | 98 |
| frontmatter_compliance | 97 |
| common_rules_compliance | 78 |
lint は FAIL 0 / WARN 0。指摘は HIGH 2件、MEDIUM 4件、LOW 3件だった。
HIGH の1件目は、複数モデルへ同一内容を投入した証拠が残らない設計だったこと。投入コマンド中の変数がどこで定義されるか書かれておらず、本当に同じプロンプトを渡したか事後確認できなかった。プロンプトを <slug>.prompt.md として確定し、全モデルが同じファイルを読む形へ変えた。
2件目は、法令要件の検査が opt-in だったこと。PR 表記を確認するフラグを付け忘れると、そのまま PASS になる。既定を有効にし、アフィリエイトリンクがない記事だけ --no-affiliate で外す向きへ反転した。法令要件をデフォルト無効にしていた設計ミスだった。
レビューには価値があった。しかし 88/100 で合格し HIGH も修正した状態は、実運用で壊れないことの証明にはならなかった。
走らせて出た5件
1. 草稿を保存する工程がなかった
SKILL.md には統合後に加筆箇所を記録する指示があったが、採点対象となる草稿そのものを保存する指示がなかった。
外部モデルへ投げる仕組みの出力は、セッションの一時ファイルにしか残らない。保存しないまま採点すると、採点表は残っても判断の根拠を後から確認できない。
どう見つかったか: 1本目の運用で踏んだ。同セッション中だったため復元できたが、次のセッションでは取り出せない。採点前に drafts/ へ保存する工程を追加し、抽出を scripts/extract-draft.sh に置いた。
2. ブリーフと検査スクリプトが矛盾していた
救出した草稿を check.sh へ通したところ、4本中3本が「H1 がない」で落ちた。
検査スクリプトは記事タイトルとして H1 を要求していた。一方ブリーフには「見出しは H2・H3 のみ」と書かれ、H1 を禁じていた。H1 を付けなかった3モデルは指示に忠実だっただけで、H1 を付けた1本のほうがブリーフから外れていた。
さらに、機械チェックを実行する前の採点では、タイトルがないことをモデル側の欠陥として減点していた。ブリーフの欠陥をモデルの欠陥として採点していたことになる。
どう見つかったか: 草稿を保存し、check.sh を実際に走らせたとき。欠陥1を直したことが、欠陥2の発見条件になっている。 保存していなければ検査にかけられず、検査にかけなければ矛盾は出ていない。
3. ファイル上で正しいシェル片が、読み込み後に壊れた
SKILL.md 本文に位置パラメータ（ドル記号と数字）を含むシェル片を直書きすると、skill の読み込み時に置換される。実際には awk で行全体を指す変数がエージェント名へ置き換わり、配布された本文の抽出コマンドが壊れていた。
どう見つかったか: skill を実際に読み込ませたとき。元のファイルを開くと記述は正しいままで、ソースの読み返しでは原理的に発見できない。シェル片を scripts/ へ移し、本文には呼び出し手順だけを残した。
4. 抽出スクリプトが本文を途中で切っていた
ここから2件は、この記事を書く過程で出た。
欠陥1の対策として作った extract-draft.sh は、出力の終端記号以降を落とす。ところが、あるモデルの草稿が記事本文の中でその終端記号に言及していた。スクリプトは最初の出現で打ち切るため、本文がそこで切れた。
3,813字（実際） → 2,041字（抽出後）本文の46%が失われていた。終端記号を行頭に限定して修正した。
どう見つかったか: 抽出した草稿を機械チェックへ通し、字数不足で落ちたとき。このとき、あやうく「そのモデルは字数不足」と採点するところだった。 欠陥2とまったく同じ、ハーネスの欠陥をモデルの欠陥として扱う形である。
5. 草稿ファイルがプロジェクト指示として読み込まれた
草稿を claude.md というファイル名で保存していた。macOS のファイルシステムは大文字小文字を区別しないため、これが CLAUDE.md——プロジェクト全体の指示ファイル——と同一視され、草稿の内容がエージェントへの指示として読み込まれていた。
どう見つかったか: 保存した直後、読み込まれた内容の中に草稿本文が現れたとき。ファイル名を claude-subagent.md へ変更した。他のモデル名では衝突しない。
発見手段ごとに、見つかる欠陥が違った
5件を、何によって見つかったかで並べ直すと分かれる。
| 発見手段 | 見つけた欠陥 |
|---|---|
| 別コンテキストの evaluator | 同一投入の保証、法令検査の既定値（HIGH 2件） |
| 全工程の実行 | 保存工程の欠落（1） |
| 機械チェックの実行 | ブリーフとの仕様矛盾（2）、抽出の打ち切り（4） |
| 読み込み後の内容確認 | シェル片の置換（3）、ファイル名の衝突（5） |
| ソースの読み返し | なし |
どの手段も、他の手段では見つからない欠陥を見つけている。 そして読み返しだけは1件も見つけていない。
もう1つ、この5件には共通の形がある。うち3件は「ハーネスの欠陥をモデルの欠陥として扱いかけた」（2の H1、4の字数、そして2に伴う実際の誤審1件）。検査を作ると、検査自体が誤審の発生源になる。落ちたときに出力側だけを疑うと、原因が仕様側にある場合に必ず間違える。
手元で同じ確かめ方をする順序
- 検査可能な制約と、文章の型になる指定を分ける。判定が独立したファイルになっていると、本文との食い違いが表に出る
- 自己採点で終わらせず、別コンテキストの evaluator へ渡す
- 指摘を直したあと、全工程を実データで1回動かす
- 中間生成物を採点前にファイルへ保存する。保存していないものは検査にかけられない
- 保存したものを機械チェックへ通す。落ちたときは、落ちた側（出力）と要求した側（仕様）を両方疑う
- ソースファイルだけでなく、読み込まれた後の内容を確認する
4と5の順序が効いている。5件のうち2件は、この2つを踏まなければ出ていない。
この記録から言える範囲
観測したのは run-article-harness という1つの skill を1回作成し、記事2本の運用を通した結果に限られる。すべての skill が同じ壊れ方をするという結果ではない。件数も内訳もこの1件のものである。
確認できたのは次の3点。
- 別コンテキストのレビューで 88/100 を取り、指摘を修正した後でも、実際に走らせると欠陥が5件出た
- 5件とも、ソースファイルの読み返しでは発見できなかった
- 発見手段ごとに、見つかる欠陥の種類が違った
この範囲で言えるのは、書き終えた状態と、走らせて直した状態は別物だということまでである。skill が完成したかどうかは、本文を読んでも判定できない。
出典
.claude/skills/run-article-harness/（NOTES.md/SKILL.md/scripts/check.sh/scripts/extract-draft.sh）sites/a-ai-works/articles/2026-08-15_multi-ai-delegation.notes.md- 欠陥4・5 は本記事の執筆中に発生したため、上記ソースには含まれない