Anthropicはついに彼らの内部スキル手法論を公開しました

見了一篇 Anthropic チームが書いたブログ《Lessons from building Claude Code: How we use skills》。これは今まで見た中で Skill に関する最も深い実践まとめだと思う。

Skill というものは実はそんなに複雑じゃない。でも、本当に Skill をうまくやりたいなら、簡単ではないと感じる。

Skill が流行り始めた頃、みんな特にいろんな文体 Skill、書き方 Skill を作るのが好きだった。まるで自分の書き方をモデルに埋め込めば、安定してそのスタイルで出力できると思っていた。

でも後になって自分で試してみると、多くの場合全然うまくいかないことに気づいた。

なぜなら、一つの文体 Skill には数千字、あるいは万単位の内容を詰め込むこともあるからだ。Skill をロードすると、文脈の一部を占めてしまう。文脈が重くなると、モデルの思考能力が逆に落ちやすくなる。

結果的によく起こるのは、スタイルは学習できたけど、内容が浅くなり、分析能力も弱くなるという状況だ。

もう一つよくあるケース。

多くの人が Skill を書くとき、操作手順や操作説明を詰め込みすぎる。

例えば：

1、最初のステップは何をするか
2、次のステップは何をするか
3、最後のステップは何をするか

こうなると、実行してみるとモデルの動きが安定しないことが多い。

後になって理解したのは、多くの繰り返し作業は、むしろ Instructions ではなく Script に落とし込む方が適しているということだ。

Anthropic の記事を読んだ後の最大の感想は、多くの人は実は Skill を使っているけど、その本質を理解していないことが多いということだ。

Skill の本質は Context Engineering である。いつ知識を Skill に入れるべきか、いつ References に分解すべきか、いつ Script にすべきか、いつ Gotchas でモデルを制約すべきか、これらには多くの経験が詰まっている。

Skill の動作原理を理解した上で、優れた Skill を振り返ると、それらが解決しているのは単なるプロンプトの問題ではなく、文脈、経験の蓄積、能力の再利用の問題だと気づく。

もし皆さんが Skill を深く研究したいなら、特におすすめの二つの記事がある。

#01 無駄話を書かない

Skill は本質的に組織内の「暗黙知」を蓄積するものだ。だから、すでに知っている常識を繰り返して書く必要はない。本当に価値があるのは、モデルが知らない情報だ。

Anthropic はよく強調するが、Skill に書くべきなのは Gotchas、つまりよく陥る落とし穴だ。

例えば：

1、この表は created_at でソートしない
2、staging で 200 が返っても成功を意味しない
3、request_id と trace_id は同じもの

これらの情報は多くの場合、社員の経験に由来するものだ。だから、Skill の本質を忘れないこと。

Skill = 熟練者の経験を書き下すこと。

Skill を通じて、散らばっていた経験を一つに蓄積する。

#02 Skill は実は Context Engineering

これが Anthropic の最も深い見解の一つだ。

Skill は単なる markdown ファイルではなく、フォルダだ。Skill を使ったことのある人には、これは当たり前の話に聞こえるかもしれない。

しかし、私はこの数日間、何度も考え直して、次第に気づいた：彼らはこのフォルダという形式を使って、Context Engineering の理念を表現しようとしているのだ。

もう一度、典型的な Skill の構造を見てみよう。

skill/  ├── SKILL.md  ├── references/  ├── scripts/  ├── examples/  ├── assets/

このとき、モデルは最初に SKILL.md を読む。もしすべての情報をこのファイルに詰め込むと、すぐに文脈が爆発的に増える。

例えば、支払いトラブル解決の Skill だとしよう。Stripe のエラーコードの説明、過去の故障例、トラブルシューティングのスクリプト、最終的なレポートテンプレートなどが含まれる。

これらすべてを SKILL.md に詰め込むと、毎回 Skill を呼び出すたびに Claude は再び読み直さなければならない。

たとえユーザーがエラーコードの意味だけ確認したい、あるいは支払いステータスの更新理由だけ見たい場合でも、役に立たない情報まで文脈に詰め込まれる。

一方、Anthropic の考え方は全く違う。

SKILL.md はあくまでナビゲーションページの役割だ。モデルに対して、「Stripe のエラーが出たら references で該当の説明を探せ」と指示する。

過去の事例を参照したいときは examples で類似の問題を調べ、実際に排障作業を行う必要があるときは scripts のスクリプトを実行し、最後に assets のテンプレートを使ってレポートを生成する。

この一連の流れは段階的に露出される。

この図をぜひ保存してほしい。

#03 なるべくスクリプトを使おう

モデルに限られた文脈と推論能力を、繰り返し作業に浪費させてはいけない。それらはスクリプトに任せる。

例を挙げると、多くの人が Skill を書くとき、こう書く。

1、登録データをクエリ
2、支払いデータをクエリ
3、コンバージョン率を計算
4、異常の原因を分析

この書き方はもちろん問題ない。モデルもできる。でも、毎回実行するたびに、最初から分析フローをやり直す必要がある。

データのクエリ、整理、境界条件の処理、これらはすべて繰り返しの作業だ。

これらの能力はすでに何度も検証されているのだから、なぜモデルにもう一度発明させる必要があるのか？ 具体的なスクリプトを提供した方が良い。

また、スクリプトを使えば、Skill の実行もより正確になり、Token も節約できる。

この観点から、Skill の Scripts は組織の能力を蓄積するものだ。各スクリプトは、過去に多くの失敗を経験し、最良の実践としてまとめられたものだ。

これらの能力を固めておけば、Claude は毎回これらの経験の上で動き、ゼロからやり直す必要がなくなる。

だから、私はますます思う。Skill の Instructions と Scripts は、異なる層の問題を解決している。

Instructions は経験と判断を提供し、Scripts は能力と実行を担う。

例えば、支払いトラブル解決の Skill にこんな一文があるとしよう。

「Stripe が 200 を返しても、支払い成功とみなさず、payment_events 表をさらに確認せよ」

これは Instructions にあたる。経験に基づく指示だからだ。一方、check_payment_events() は Script であり、実行能力を持つ。

もし Script だけなら、どうやって調べるかはわかるが、なぜ調べるのかはわからない。

Instructions だけなら、何をすべきかはわかるが、毎回自分で再実装しなければならない。両方が必要だ。

#04 Description はルーティングルールのようなもの

多くの人が Skill の Description の書き方を誤っている。

なぜなら、機能紹介をそのまま書きがちだからだ。例えば：PR Management Skill は、「PR 状態を監視し、CI 問題を処理し、自動マージを行う」と紹介する。

しかし、問題はモデルは Skill の機能から探すわけではないことだ。Claude Code は起動時に、すべての Skill の名前と Description をスキャンする。

そして、ユーザーの現在の問題に基づいて、どの Skill をロードすべきか判断する。

だから、Description で最も重要なのは、「この Skill を使うべき状況は何か」だ。

Description は、実は Skill のルーティングを担っている。

現実の世界では、「PR 管理ツールを呼び出して」と頼む人は少なく、「この PR や CI の状況を見てほしい」と言う方が多い。

だから、良い Description とは、ユーザーの意図をできるだけ正確に表現し、機能の羅列ではなく、使いたい場面を示すべきだ。

私も一つ簡単なチェック方法を提案したい。

Description を書いたら、その Skill を削除して、ただ一行の Description のみ残す。

そして、自分に問いかける：「この Description を見て、ユーザーの問題からいつこの Skill を使うべきか理解できるか？」

もしできなければ、まだ改善の余地がある。

#05 Skill の管理と配布

最後に、Skill の管理について。

一人で Skill を使うなら、これは非常にシンプルだ。いくつかの Skill を書いて、自分でメンテし、自分でアップデートすれば良い。

しかし、多くのチームでは、同じ問題に直面するだろう。

Skill が数個から数十個、あるいは数百個になったとき、これらをどう管理し、どうアップデートし、どうチームに配るか。

Anthropic の経験は非常に参考になる。

小規模なチームなら、Skill はコードリポジトリと一緒に管理する。.claude/skills ディレクトリに置いて、みんなで共有する。

しかし、Skill の数が増えると、新たな問題が出てくる。

Claude Code の起動時に、すべての Skill の名前と Description をスキャンし、どの Skill を呼び出すか判断する。Skill が増えれば増えるほど、ルーティングのコストが高くなる。

これが、後に Marketplace を作る理由だ。でも、もっと面白いのは、その管理方法だ。

多くの企業は、まず承認フローを作る。誰が Skill を作ったか申請させ、承認されたら公式 Skill ライブラリに登録する。

私たちも以前やったが、これは非常に重い管理方法だ。

Anthropic の組織は、もっと軽やかだ。

新しい Skill はまず小さな範囲で展開し、同僚が自分でインストールして試用させる。

多くの人が使い始めて、実際に問題解決に役立つと判断されたら、その時点で正式な Marketplace に登録する。

つまり、最初から価値の有無を議論するのではなく、実際の使用シーンで試してもらい、多くの人に使われてから正式化する。そうすれば、残る Skill は本当に必要なものだけになる。