Claude Skillsが壊れる原因｜業務で使い続ける直し方

「部署で作ったスキルが、いつの間にか途中で止まるようになった」「作った人が異動して、どこを直せばいいか誰も分からない」。スキルを業務に配り始めて半年ほどたった会社で、こうした声が出始めています。きっかけははっきりしています。アンソロピックは2025年10月に、手順と参照資料と小さなプログラムを1つの束にして、必要なときだけクロードに読み込ませるエージェントスキルを公開しました。同年12月には、組織での管理の仕組みと、他のAIの道具でも同じ形で使える公開仕様を追加しています。報告書の書式、問い合わせの仕分け、月次の集計といった社内の手順をスキルにして、部署や全社に配る会社が増えたのはこの流れの上です。ただ、ここで見落とされやすい点があります。スキルは一度作れば終わる部品ではありません。本当は、前提にしているモデル・道具・業務の側が動くので、点検しないと静かに壊れるものです。この記事では、スキルが壊れる原因を6つの型に分け、症状から原因をたどる方法、止めるか直すかの判断、直し方と直した状態を保つ記録の付け方を整理します。

スキルは「一度作れば終わる部品」ではない

スキルの中身は、文章で書いた手順と、参照する資料と、決まった処理をする小さなプログラムです。どれも作った時点で固まっていて、誰かが書き換えない限り変わりません。それなのに壊れるのは、スキルが単独では動かず、外側のものに寄りかかって動いているからです。読むのはその時々のモデルで、プログラムが動くのは使う場所の環境で、手順が前提にしているのは作った時点の業務です。

この3つは、いずれもスキルを作った会社の都合では止まりません。モデルは提供元の判断で新しい版に替わり、道具やつなぐ先の仕様は相手の都合で変わり、業務は組織変更や取引先の要望で変わります。アンソロピックの公式の手引きも、スキルは土台のモデルへの追加物なので、効き方は土台のモデルに左右されると書き、使う予定のモデルすべてで試すよう求めています。企業向けの手引きでは、業務とモデルの変化で劣化するので、評価を定期的に回し直すよう書かれています。

つまり、スキルは置いておけば同じ結果を出し続ける部品というより、周りの変化に合わせて手入れを続ける道具に近いものです。自動化が止まる原因を、モデルそのものではなくモデルを動かす周りの仕組みの側に見る考え方は、ハーネスエンジニアリングとはで整理しています。この記事は、その考え方をスキルという具体的な形に当てはめて、作った後に壊れる側だけを扱います。

仕組みは3層：説明文・本文・付属物

壊れ方を見分けるには、スキルがどう読み込まれるかを最低限知っておく必要があります。公式の説明では、スキルは3つの層に分かれ、層ごとに読み込まれる時期が違います。1層目は名前と説明文で、起動時に常に読み込まれ、1件あたりおよそ100トークンを使います。2層目は手順の本文で、依頼の内容が説明文と合ったときに初めて読み込まれます。3層目は参照ファイルやプログラムで、本文の中で必要になったときだけ開かれます。

この仕組みから分かるのは、スキルが使われるかどうかは、説明文1つで決まるということです。公式の説明でも、クロードは依頼を説明文と照らしてスキルを呼ぶかどうかを決めるので、説明文には何をするかと、いつ使うかの両方を書くよう求めています。説明文は最大1,024文字で、本文は5,000トークン未満が目安とされています。プログラムは中身が読み込まれず、実行した結果だけがクロードに渡ります。

もう1つ押さえておきたいのは、スキルを置く場所が3つに分かれていることです。2026年10月時点の公式の説明では、ウェブ版やアプリ、開発者向けの API、手元で動かすクロードコードのそれぞれに別々に置く必要があり、1か所で直しても、他の場所に置いた同じスキルは古いままです。共有できる範囲も場所ごとに違います。どの作業をスキルにするか、置き場所と共有範囲をどう決めるかは、手順書を渡すかスキルで持たせるかで扱っています。

壊れ方は「止まる」より「静かにずれる」

スキルの壊れ方は、大きく5つの症状に分かれます。1つ目は、呼ばれるはずの依頼で呼ばれなくなる。2つ目は、別のスキルが呼ばれる、あるいは関係のない依頼で呼ばれる。3つ目は、呼ばれるが手順の一部を飛ばす。4つ目は、途中で止まる、あるいは誤りの表示で終わる。5つ目は、最後まで動くが、出てきた成果物の中身が違う。

このうち、はっきり目に見えるのは4つ目だけです。残りの4つは、誤りの表示が出ないまま、それらしい結果が返ってくるので、使う人が気づきにくい壊れ方です。呼ばれなかった場合も、クロードはスキルなしで依頼に答えようとします。答えの形は整っているので、決まった書式や除外条件が抜けていることに、受け取った人がすぐ気づくとは限りません。

クロードコードの公式の説明には、静かな壊れ方の分かりやすい例が載っています。スキルの冒頭にある設定欄の書き方が崩れていると、名前を指定して直接呼べば本文は読み込まれるものの、説明文が空として扱われ、依頼と照らして自動で呼ぶことができなくなる、というものです。作った人が名前で呼んで試すと動くので、作った人の手元では動き、他の人の依頼では呼ばれないという食い違いが生まれます。

原因1：説明文が曖昧で呼ばれない・取り合う

もっとも多いのは、説明文に原因がある壊れ方です。作った時点では、依頼の言い方と説明文がたまたま合っていて呼ばれていたものが、使う人が増えて言い方がばらけると呼ばれなくなります。説明文に「報告書を作る」とだけ書いてあると、「月次のまとめを出して」という依頼とは結びつきにくいのです。公式の手引きは、説明文に使う人が自然に口にする言葉を入れ、何をするかといつ使うかの両方を書くよう求めています。

逆向きの壊れ方もあります。スキルが増えるにつれて、似た説明文のスキルが並び、新しく足したスキルが古いスキルの出番を奪うことです。企業向けの手引きは、説明文が広すぎる新しいスキルが既存のスキルの呼び出しを奪う例を挙げ、同時に読み込むスキルの数を絞るよう書いています。名前と説明文は常に読み込まれ、呼び出しの判断の材料として互いに競り合うので、数が増えるほど正しいものが選ばれにくくなります。開発者向けの API では、1回の依頼で使えるスキルは20件までと決められています。

説明文の長さにも落とし穴があります。クロードコードでは、説明文と「いつ使うか」の欄を合わせた文字が、スキルの一覧の中で1,536文字で切られると公式に書かれています。条件を細かく書き足すほど、後ろに書いた使いどころが切れて読まれなくなります。同じ名前のスキルが会社・個人・案件の置き場所に重なっている場合は会社のものが優先されるので、直したはずのスキルとは別の版が呼ばれていることもあります。

原因2：モデルの版で読み方が変わる

スキルの本文は、その時々のモデルが読んで解釈します。モデルが新しい版に替わると、同じ本文でも読み方が変わります。以前のモデルが暗黙に補っていた手順を新しいモデルが飛ばすこともあれば、逆に慎重になって確認を求める回数が増え、途中で止まったように見えることもあります。公式の手引きは、上位のモデルで十分に動く書き方でも、軽いモデルではもっと詳しく書く必要があるかもしれない、と書いています。

この原因が厄介なのは、スキルの側に変更の記録が何も残らないことです。誰も本文を触っていないので、変更の履歴を見ても何も出てきません。壊れた時期とモデルの切り替わった時期を並べて初めて、原因の見当がつきます。だからこそ、スキルを使った記録に、どの版のモデルで動かしたかを残しておく意味があります。

モデルの版が変わったときの点検は、スキルに限らずAIを使う仕組み全体で必要になります。乗り換えの段取りと点検する項目の一覧はAIのモデル乗り換えで点検する項目で整理しているので、ここではスキルに固有の点だけを挙げます。スキルでは、モデルが替わったら後で触れる評価の場面を回し直し、呼ばれ方と手順の守られ方の両方を確かめます。本文を書き換えるのは、評価で落ちた箇所が見つかってからにします。

原因3：参照ファイルが古くなる

スキルの3層目に置いた参照ファイルは、業務の変化をいちばん受けやすい部分です。価格表、部署の名前、取引先ごとの決まり、審査で弾かれた表現の一覧。こうした中身は、業務の側で変わってもスキルの中には自動で反映されません。人が読む資料なら古さに気づけますが、スキルは古い資料を、書いてあるとおりに正確に使い続けます。誤りの表示は出ず、古い価格で見積もりの下書きができあがります。

公式の手引きは、時期によって変わる情報を本文に書かないよう求めています。たとえば「何月までは古い方式、それ以降は新しい方式」と書くと、いずれ誤りになるからです。代わりに、現在の方式を本文に書き、古い方式は「古い手順」として別の欄に分けておく形が示されています。日付の条件を本文に埋め込んだスキルは、その日付を過ぎた時点で壊れると考えておくとよいでしょう。

参照の仕方そのものも壊れる原因になります。公式の手引きによると、本文から参照したファイルの中でさらに別のファイルを参照する入れ子の形にすると、クロードがファイルの先頭だけを読んで済ませ、情報が欠けることがあります。参照は本文から1段だけにし、100行を超える参照ファイルには冒頭に目次を置くよう書かれています。後から資料を足していくうちに入れ子が深くなり、ある日から一部の決まりが守られなくなる、という壊れ方はこの形から起きます。

原因4：プログラムの依存・つなぐ先・認証が変わる

スキルに同梱した小さなプログラムは、動きが一定になるという利点がある一方で、環境の変化をまともに受けます。必要な部品が入っていない、つなぐ先の仕様が変わった、鍵の期限が切れた。どれもスキルの中身とは関係なく起き、多くは途中で止まる形で表に出ます。公式の手引きは、プログラムの中で誤りを自分で処理し、クロードに丸投げしないよう求めています。誤りの扱いが書かれていないプログラムは、止まったときにクロードがその場で回り道を考え、毎回違う結果を返すことがあるためです。

使う場所による違いも見落とされがちです。2026年10月時点の公式の説明では、開発者向けの API で動くスキルは外部への接続ができず、実行中に部品を追加することもできません。一方、クロードコードでは利用者のパソコンと同じように外部に接続できます。ウェブ版は管理者や利用者の設定によって接続の可否が変わります。クロードコードで作って動いたスキルを API に置くと、外部への接続で止まるというのは、この違いから起きる典型です。

外部の道具をつなぐ仕組み（MCP）を使うスキルでは、道具の名前の書き方も壊れる原因になります。公式の手引きは、道具をサーバーの名前付きで書かないと、つないでいるサーバーが複数あるときに見つからないことがあるとしています。最初は1つしかつないでいなかったので動いていたものが、別の道具を追加した日から止まる、ということが起きます。さらに、外部の場所から中身を取ってくるスキルは、取ってくる先が変われば、信頼できる作り手のものでも危うくなると公式は注意しています。

原因5：完了の条件と確かめ方が書かれていない

手順だけを書き、何をもって終わりとするか、終わったことをどう確かめるかを書いていないスキルは、モデルや業務が少し動いただけで崩れます。手順は「何をするか」の羅列なので、途中の1つを飛ばしても、本人は最後まで済ませたつもりで「完了しました」と返します。完了の条件がないと、途中で終わったことと最後まで終わったことの区別がつかないのです。

公式の手引きは、込み入った作業では手順をチェックリストにし、クロードに写させて1つずつ消し込ませる形と、検証のプログラムを走らせて誤りがあれば直し、通るまで繰り返す形を示しています。大事なのは、確かめる役を手順の中に置くことです。たとえば集計のスキルなら、最後に合計が元の表と一致するかを決まったプログラムで確かめ、一致しなければ先に進まない、という一行を本文に書きます。

ここで線を引いておきたいのは、確かめる役を、作業したAI自身の自己申告にしないことです。「確認しました」と書かせるだけでは確認になりません。数の一致、必須項目の有無、書式の検査のように、機械で白黒がつく確かめ方を同梱するか、人が確かめる箇所を本文に名指しで書きます。取引先に出す文面の最終稿、公表する数字、価格の決定のように、スキルに判断させない工程も、業務の名前で本文に書いておきます。

原因6：持ち主がいない

最後の型は、技術ではなく体制の問題です。スキルは作った人の手元で生まれ、部署に配られた時点で「みんなのもの」になります。作った人が異動したり忙しくなったりすると、壊れても直す人がいません。冒頭の「どこを直せばいいか誰も分からない」は、この型の典型です。持ち主のいないスキルは、壊れていることに気づいた人がいても、直してよいのか判断できずに放置されます。

企業向けの手引きは、スキルごとに目的・持ち主・版・依存先・最後に評価した日と結果を台帳に残すよう書いています。また、作った人が自分の審査役を兼ねないよう、職務を分けることも求めています。持ち主は、直す作業を自分でする人である必要はありませんが、止めるか直すかを決め、直した結果を受け入れる責任を持つ人です。

持ち主を決めても、社内に直せる人がいない場合は、外の力を借りることも選択肢になります。業務と一緒にスキルの中身を読み解き、点検して作り直すところまでを伴走で引き受ける支援もあり、デボノのAI推進BPOもその1つです。いずれにしても、持ち主と台帳を社内に残しておけば、誰が直しても次の人が引き継げます。

症状から原因をたどる対応表

6つの原因の型は、表に出る症状から逆にたどれます。次の表は、症状ごとに疑う順番と、最初に見る場所を並べたものです。原因は1つとは限りませんが、上の行から順に疑うと、手間の少ない確認から済ませられます。

症状	まず疑う原因	最初に見る場所	次に疑う原因
呼ばれるはずの依頼で呼ばれない	説明文（原因1）	説明文と、実際の依頼の言い方。冒頭の設定欄の書き方	同名の別のスキルが優先されていないか
別のスキルが呼ばれる・無関係な依頼で呼ばれる	説明文の取り合い（原因1）	似た説明文のスキルの一覧と、最近足したスキル	同時に読み込むスキルの数
呼ばれるが手順を飛ばす	モデルの版（原因2）	壊れた時期とモデルの切り替わった時期	完了の条件がない（原因5）
途中で止まる・誤りの表示で終わる	プログラムの依存・接続・鍵（原因4）	止まった地点の記録と誤りの文面	使う場所の違い（接続の可否）
最後まで動くが中身が違う	参照ファイルが古い（原因3）	参照ファイルの更新日と、業務の側の変更	参照の入れ子
「完了」と返るが一部が抜けている	完了の条件がない（原因5）	本文に確かめ方が書いてあるか	モデルの版（原因2）
壊れているのに誰も直さない	持ち主がいない（原因6）	台帳の持ち主の欄	直せる人が社内にいるか

表を使うときの注意は、症状を見た人の言葉をそのまま信じないことです。「動かない」という報告は、呼ばれていないのか、途中で止まったのか、中身が違うのかで原因がまったく変わります。最初に、どの症状なのかを使った記録で確かめることから始めます。記録がなければ、同じ依頼をもう一度出して、呼ばれたスキルと止まった地点を見ます。

直す前に止める。止めるか直すかは人が決める

壊れたと分かったスキルは、直す前にまず止めるかどうかを決めます。誤った成果物を作り続けるスキルを動かしたまま直すと、直している間にも古い価格の見積もりや、除外条件の抜けた集計が配られます。とくに、外に出る文書を作るスキルや、送信・登録のような元に戻せない操作を含むスキルは、原因の見当がつく前に止めるのが安全です。

戻し先があれば、止めるかわりに前の版に戻す手もあります。企業向けの手引きは、本番で使うスキルは版を固定し、前の版を戻し先として残しておくよう書いています。開発者向けの API で版を指定しない場合は最新の版が使われるので、誰かが新しい版を置いた瞬間に、本番で動くものが変わると注意しています。版を固定していれば、壊れたときに「最後にちゃんと動いた版」へすぐ戻せます。

止めるか、戻すか、動かしたまま直すか。この判断はAIにも作った人1人にも任せず、台帳に書いた持ち主が決めます。スキルの業務への使い方で、人が決めることは次の4つです。

1. どの業務をスキルにするか。止まったときの影響が大きい業務ほど、確かめ方を同梱できるまでスキルにしない
2. スキルに判断させない範囲。価格の決定、外に出す文面の最終稿、公表する数字の確定などを業務の名前で決める
3. 配る範囲と、作ってよい人。個人の手元で試すのは自由でも、部署や全社に配るときは持ち主と審査役を決める
4. 壊れたときに止める判断。止める権限を持つ人を、持ち主とは別にもう1人決めておく

直し方の手順

止めた、あるいは前の版に戻したら、原因の層を特定して直します。思いついた箇所から本文を書き換えると、直ったのか偶然通ったのかが分からなくなるので、次の順番で進めます。

この手順で抜けやすいのは、最後の「ほかの場所に揃える」です。公式の説明のとおり、スキルは使う場所の間で同期しないので、クロードコードで直したスキルを API やウェブ版に置き直さないと、直したはずの壊れ方が別の場所で続くことになります。企業向けの手引きは、スキルの元のファイルを版管理の仕組みに置き、そこを唯一の正本にして、各場所へ自分たちで揃える手順を作るよう書いています。

修正の下書きをAIに任せるのはかまいません。説明文の言い換えの案や、完了の条件の書き方の案は、AIに出させると速く進みます。ただし、どの層が原因かを決めるのと、直した結果を受け入れるのは人です。直したAIに「直りました」と言わせて終わりにせず、評価の場面で白黒をつけます。

直したら3種類の場面で確かめる

直したかどうかを確かめる場面は、事前に作っておきます。企業向けの手引きは、1つのスキルにつき3〜5件の代表的な依頼を用意し、呼ばれるべき場面、呼ばれるべきでない場面、どちらとも取れる場面を含めるよう求めています。見る観点は、呼ばれる正確さ、単独で動くか、ほかのスキルと並べても邪魔をしないか、指示どおりに動くか、出てきた成果物の質の5つです。

公式の手引きによると、こうした評価を回す組み込みの仕組みはなく、各社が自分で用意するものとされています。難しく考える必要はありません。依頼の文面と、期待する振る舞いを3つほど箇条書きにした表があれば足ります。この表があるかないかで、直したかどうかの判断が感覚から事実に変わります。直すたびに別の業務が壊れないかを確かめる回帰テストの組み方は、AIエージェントの回帰テストとはで詳しく扱っています。

確かめるときにやりがちな失敗を挙げておきます。

• 直したAIに、直ったかどうかの判定もさせる。作った本人の採点になり、落ちている箇所が見えない
• 呼ばれるべき場面だけを試す。説明文を広げた結果、ほかのスキルの出番を奪っていることに気づかない
• 作った人の言い方で依頼を書く。使う人の言い方では呼ばれないことが、評価では見えない
• 上位のモデル1つで試して終える。軽いモデルを使う部署では手順が飛ぶ
• 1か所で直して評価を通し、ほかの場所に置いた同じスキルを古いまま残す

直した状態を保つ台帳：持ち主・版・依存先・評価日

直したスキルが再び静かに壊れるのを防ぐには、1件ずつ記録を残す台帳が要ります。企業向けの手引きが挙げる項目は、目的、持ち主、いま配っている版、依存先、最後に評価した日と結果の5つです。依存先には、外部の道具をつなぐ仕組み、必要な部品、つなぐ外部のサービスを書きます。依存先の欄が埋まっていれば、つなぐ先の仕様変更の知らせを見たときに、影響を受けるスキルをすぐ洗い出せるようになります。

台帳の項目に、もう2つ足しておくと点検が楽になります。1つは、評価を回したときのモデルの版です。もう1つは、置いてある場所の一覧です。この2つがあれば、モデルが替わったときに回し直すべきスキルと、直したときに揃えるべき場所が一目で分かります。

点検は、決まった周期に加えて、引き金を決めて回します。引き金になるのは、モデルの版が替わったとき、依存先の仕様が変わったとき、参照ファイルの元になる業務の決まりが変わったとき、新しいスキルを足したときの4つです。新しいスキルを足したときに既存のスキルを回し直すのは見落とされがちですが、説明文の取り合いはこのときに起きます。使われていないスキルを片付ける担当や、更新の担当の決め方は、先に挙げた手順書とスキルの記事で扱っているので、ここでは台帳の中身に絞ります。

点検のチェックリスト

配っているスキルを点検するときは、次の項目を1件ずつ確かめます。上の4つは人が決めることで、技術の担当だけでは埋まりません。埋まらない項目があるスキルは、中身を直す前に、持ち主と判断の線を決めるほうが先です。

• 持ち主が決まっていて、その人が止めるか直すかを決められる
• スキルに判断させない工程が、業務の名前で本文に書いてある
• 配っている範囲と、作ってよい人・審査する人が分かれている
• 壊れたときに止める権限を持つ人が決まっている
• 説明文に、何をするかと、使う人が口にする言い方でいつ使うかが書いてある
• 似た説明文のスキルが並んでいない。同じ名前のスキルがほかの置き場所にない
• 本文に日付の条件を埋め込んでいない。参照は本文から1段だけになっている
• 完了の条件と、機械か人による確かめ方が本文に書いてある
• プログラムが誤りを自分で処理し、依存先が台帳に書いてある
• 3種類の場面の評価があり、使うモデルすべてで最後に回した日が分かる
• 置いてあるすべての場所で、同じ版になっている

すべてを一度に満たす必要はありません。まずは配っているスキルを一覧にし、持ち主の欄と最後に評価した日の欄だけを埋めてみてください。この2つの欄が空いているスキルが、次に壊れる候補です。

直せる人が社内にいないときの頼み先

ここまでの点検と直し方は、スキルの中身と業務の両方を分かっている人がいて初めて回ります。ところが実際には、作った人は異動し、残った人は業務は分かってもスキルの層の見分け方が分からない、という状態で止まっていることが少なくありません。説明文を直せば済むのか、業務の手順から作り直すべきなのかは、業務を一緒に見ないと決められません。

こうした相談を受ける枠として、デボノはAI推進BPOを用意しています。放置されて動かなくなったスキルや定期実行、エージェントを、業務と一緒に見ながら、指示・道具・確かめ方・止め方・記録の順に点検して作り直す、という進め方もこの枠で扱えます。

まとめ

スキルは、中身を誰も触っていなくても壊れます。読むモデル、動く環境、前提にしている業務という外側が動くからです。壊れ方の多くは止まるより先に静かにずれる形で表れ、原因は説明文・モデルの版・参照ファイル・プログラムの依存・完了の条件・持ち主の6つの型にほぼ分かれます。症状から原因の層をたどり、止めてから、その層だけを直し、3種類の場面で確かめて版を上げる。この順番を守れば、直したかどうかを感覚でなく事実で判断できます。修正の下書きはAIに任せてもかまいませんが、どの業務をスキルにするか、判断させない範囲、配る範囲と作ってよい人、壊れたときに止める判断は人が決めます。まずは配っているスキルの一覧を作り、持ち主と最後に評価した日の2つの欄を埋めるところから始めてください。

• エージェントスキルの仕組み・制限・置く場所ごとの違いは、アンソロピックの公式ドキュメント（スキルの概要、作り方の手引き、企業向けの手引き、クロードコードのスキルの説明）と公式ブログを2026年10月6日に確かめた範囲に基づきます。仕様は変わることがあるため、作業の前に公式の最新の説明を確かめてください
• 配れる範囲や管理者による一括管理の扱いは、使う場所・プラン・時期によって異なります。公式の説明の中でも記述の時期によって書き方が違うため、自社の契約で確かめてください
• 6つの原因の型、対応表、台帳に足す項目、点検の引き金は、公式の説明をもとに運用の考え方として整理した一例です

※本記事にはAIが活用されています。編集者が確認・編集し、可能な限り正確で最新の情報を提供するよう努めておりますが、情報の完全性、正確性、最新性、有用性等について保証するものではありません。本記事の内容に基づいて行動を取る場合は、読者ご自身の責任で行っていただくようお願いいたします。