著者：AIプロダクト阿颖
Anthropicチームが書いたブログ「Lessons from building Claude Code: How we use skills」を読んだ。これまで見た中で、Skillに関する最も深い実践のまとめだと思う。
Skillというものは実はそんなに複雑ではないが、実際にSkillをうまくやるのはそんなに簡単ではないと感じる。
Skillが流行り始めた頃、みんなは特にさまざまな文体Skillや執筆Skillを作るのが好きだった。自分の書き方を入れれば、モデルはそのスタイルに沿って安定して出力できると思っていた。
しかし、その後いろいろ試してみて、多くの場合それは全く実現不可能だと気づいた。
なぜなら、一つの文体Skillには数千字、あるいは万単位の内容を詰め込むことがあるからだ。Skillをロードすると、文脈の占有率が非常に高くなる。文脈が重くなると、モデルの思考能力は逆に低下しやすい。
結果としてよく起こるのは、スタイルは学習できたが、内容が浅くなり、分析能力も弱まるという状況だ。
もう一つよくあるケース。
多くの人がSkillを書くとき、さまざまな操作説明を詰め込みたがる。第一段階は何をする、第二段階は何をする、第三段階は何をする、という具合に。
しかし、実行してみると、モデルの実行が安定しないことに気づく。
そこで徐々に理解したのは、多くの繰り返し作業は、実はInstructionsではなく、Scriptに沈殿させる方が適しているということだ。
Anthropicのこの文章を読んだ後、最大の感想は、多くの人は実はSkillを使っているが、Skillの本質を理解していないことが多いということだ。
Skillの本質は、Context Engineeringを行うことにある。いつ知識をSkillに入れるべきか、いつReferencesに分解すべきか、いつScriptに書くべきか、いつGotchasを使ってモデルを制約すべきか、これらには多くの経験が詰まっている。
Skillの動作原理を理解した上で、優れたSkillを見ると、それらが解決しているのは単なるプロンプトの問題ではなく、文脈、経験の沈殿、能力の再利用の問題だと気づく。
もし皆さんがSkillを深く研究したいなら、特におすすめの二つの記事は以下だ。
#01 無駄話を書かない
Skillの本質は、組織内の「暗黙知」を沈殿させることだ。だから、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/（詳細説明、APIリファレンス、境界条件） ├── scripts/（実行可能なスクリプト） ├── examples/（例） ├── assets/（テンプレート、画像、固定素材）
特定のSkillを呼び出すとき、モデルはまずSKILL.mdを読む。もしすべての情報をこのファイルに詰め込むと、すぐに文脈爆発を起こす。
例えば、これは支払いトラブル解決のSkillだとしよう。Stripeのエラーコード説明、過去の故障例、トラブルシューティングスクリプト、最終レポートテンプレートなどが含まれている。
これらすべてをSKILL.mdに詰め込むと、毎回Skillを呼び出すたびにClaudeは再び読み直さなければならない。
たとえユーザーがエラーコードの意味だけ確認したい場合や、支払いステータスの更新がなぜされないのか見たいだけでも、多くの不要な情報も一緒に文脈に詰め込まれる。
しかし、Anthropicの考え方は全く異なる。
SKILL.mdはあくまでナビゲーションページのようなものだ。Stripeのエラーに遭遇したとき、モデルに対して「referencesの中の対応する説明を見てください」と指示する役割を果たす。
過去の事例を参照したいときはexamplesに行き、実際に排障動作を行いたいときはscriptsのスクリプトを実行し、最終的にレポートを作成するときはassetsのテンプレートを使う。
この全体の流れは段階的に露出される。
この図を、ぜひ皆さんに保存してほしい。
#03 なるべくスクリプトを使う
モデルに限られた文脈と推論能力を、繰り返し作業に浪費させてはいけない。それらの作業はスクリプトに任せる。
例を挙げると、多くの人がSkillを書くとき、こう書く。
この書き方はもちろん問題ない。モデルもできる。しかし、毎回実行するたびに、最初から分析フローをやり直さなければならない。
データのクエリ、整理、さまざまな境界ケースの処理、これらはすべて繰り返しの作業だ。
これらの能力はすでに何度も検証されているのだから、なぜモデルにもう一度発明させる必要があるのか？具体的なスクリプトを提供した方が良い。
また、スクリプトを使うことで、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管理Skillは、PRの状態監視、CI問題の処理、自動マージを支援します。
しかし問題は、モデルはSkillを機能で探すわけではないことだ。Claude Codeが起動するとき、まずすべてのSkillの名前とDescriptionをスキャンする。
そして、ユーザーの現在の問題に基づいて、どのSkillをロードすべきか判断する。
だから、Descriptionに最も重要な情報は、「このSkillは何をするか」ではなく、「どんな状況でロードすべきか」だ。
Descriptionは、実は全体のSkillのルーティングを担っている。
現実の世界では、「PR管理ツールを呼び出して」と頼む人はほとんどいない。むしろ、「このPR、CIがまた落ちてるから見てほしい」などの方が多い。
だから、良いDescriptionは、ユーザーの意図をできるだけ正確に表現し、機能の羅列は避けるべきだ。
私自身、こんな簡単な方法でチェックできると思う。
Descriptionを書いたら、そのSkillを全部削除し、その行だけ残す。そして自分に問いかける：ユーザーの問題を見たとき、モデルはこのSkillをロードすべきタイミングを理解できるか。
できなければ、さらに改善の余地がある。
#05 Skillの管理と配布
もう一つ、Skillの管理についてだ。
一人でSkillを使う場合は、実はとても簡単だ。いくつかSkillを書いて、自分で管理し、自分でアップデートすれば良い。
しかし、多くのチームでは、次第に同じ問題に直面する。
Skillが数個から数十個、あるいは数百個に増えたとき、これらをどう管理し、どうアップデートし、どうチームに配るか。
Anthropicのこの点での経験は、非常に参考になる。
小規模なチームなら、Skillはコードリポジトリと連動させる。プロジェクト内の.claude/skillsディレクトリに置けば良い。みんなで同じSkillセットを共有し、同じ作業方法を使う。
しかし、Skillの数が増え続けると、新たな問題が出てくる。
Claude Codeの起動時、すべてのSkillの名前とDescriptionをスキャンし、どのSkillを呼び出すか判断する。Skillが増えれば増えるほど、ルーティングのコストは高くなる。
これが理由で、AnthropicはMarketplaceを始めたのだが、さらに面白いのは、そのMarketplaceの管理方法だ。
多くの企業は、この問題に直面すると、まず承認フローを作る。誰がSkillを書いたか申請させ、承認後に公式Skillライブラリに登録する。
私たちも以前やっていたが、非常に重い管理だった。
Anthropicの組織は、非常に軽やかだ。
新しいSkillはまず小さな範囲で展開し、同僚が自分でインストールして試用させる。
多くの人が使い始めて、実際に問題解決に役立つと判断されたら、その段階で正式なMarketplaceに登録する。
つまり、最初から価値の有無を議論するのではなく、実運用の中で検証し、多くの人に使われて初めて正式化する。そうして残ったSkillは、ほぼ確実にチームにとって必要なSkillになる。
3.69M 人気度
499.07M 人気度
56.25K 人気度
1.33M 人気度
1.81M 人気度
ほとんどの人が書いたスキルは間違っている：Anthropicが内部の方法論を公開した後の5つの反省
著者：AIプロダクト阿颖
Anthropicチームが書いたブログ「Lessons from building Claude Code: How we use skills」を読んだ。これまで見た中で、Skillに関する最も深い実践のまとめだと思う。
Skillというものは実はそんなに複雑ではないが、実際にSkillをうまくやるのはそんなに簡単ではないと感じる。
Skillが流行り始めた頃、みんなは特にさまざまな文体Skillや執筆Skillを作るのが好きだった。自分の書き方を入れれば、モデルはそのスタイルに沿って安定して出力できると思っていた。
しかし、その後いろいろ試してみて、多くの場合それは全く実現不可能だと気づいた。
なぜなら、一つの文体Skillには数千字、あるいは万単位の内容を詰め込むことがあるからだ。Skillをロードすると、文脈の占有率が非常に高くなる。文脈が重くなると、モデルの思考能力は逆に低下しやすい。
結果としてよく起こるのは、スタイルは学習できたが、内容が浅くなり、分析能力も弱まるという状況だ。
もう一つよくあるケース。
多くの人がSkillを書くとき、さまざまな操作説明を詰め込みたがる。第一段階は何をする、第二段階は何をする、第三段階は何をする、という具合に。
しかし、実行してみると、モデルの実行が安定しないことに気づく。
そこで徐々に理解したのは、多くの繰り返し作業は、実はInstructionsではなく、Scriptに沈殿させる方が適しているということだ。
Anthropicのこの文章を読んだ後、最大の感想は、多くの人は実はSkillを使っているが、Skillの本質を理解していないことが多いということだ。
Skillの本質は、Context Engineeringを行うことにある。いつ知識をSkillに入れるべきか、いつReferencesに分解すべきか、いつScriptに書くべきか、いつGotchasを使ってモデルを制約すべきか、これらには多くの経験が詰まっている。
Skillの動作原理を理解した上で、優れたSkillを見ると、それらが解決しているのは単なるプロンプトの問題ではなく、文脈、経験の沈殿、能力の再利用の問題だと気づく。
もし皆さんがSkillを深く研究したいなら、特におすすめの二つの記事は以下だ。
#01 無駄話を書かない
Skillの本質は、組織内の「暗黙知」を沈殿させることだ。だから、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/（詳細説明、APIリファレンス、境界条件） ├── scripts/（実行可能なスクリプト） ├── examples/（例） ├── assets/（テンプレート、画像、固定素材）
特定のSkillを呼び出すとき、モデルはまずSKILL.mdを読む。もしすべての情報をこのファイルに詰め込むと、すぐに文脈爆発を起こす。
例えば、これは支払いトラブル解決のSkillだとしよう。Stripeのエラーコード説明、過去の故障例、トラブルシューティングスクリプト、最終レポートテンプレートなどが含まれている。
これらすべてをSKILL.mdに詰め込むと、毎回Skillを呼び出すたびにClaudeは再び読み直さなければならない。
たとえユーザーがエラーコードの意味だけ確認したい場合や、支払いステータスの更新がなぜされないのか見たいだけでも、多くの不要な情報も一緒に文脈に詰め込まれる。
しかし、Anthropicの考え方は全く異なる。
SKILL.mdはあくまでナビゲーションページのようなものだ。Stripeのエラーに遭遇したとき、モデルに対して「referencesの中の対応する説明を見てください」と指示する役割を果たす。
過去の事例を参照したいときはexamplesに行き、実際に排障動作を行いたいときはscriptsのスクリプトを実行し、最終的にレポートを作成するときはassetsのテンプレートを使う。
この全体の流れは段階的に露出される。
この図を、ぜひ皆さんに保存してほしい。
#03 なるべくスクリプトを使う
モデルに限られた文脈と推論能力を、繰り返し作業に浪費させてはいけない。それらの作業はスクリプトに任せる。
例を挙げると、多くの人がSkillを書くとき、こう書く。
この書き方はもちろん問題ない。モデルもできる。しかし、毎回実行するたびに、最初から分析フローをやり直さなければならない。
データのクエリ、整理、さまざまな境界ケースの処理、これらはすべて繰り返しの作業だ。
これらの能力はすでに何度も検証されているのだから、なぜモデルにもう一度発明させる必要があるのか？具体的なスクリプトを提供した方が良い。
また、スクリプトを使うことで、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管理Skillは、PRの状態監視、CI問題の処理、自動マージを支援します。
しかし問題は、モデルはSkillを機能で探すわけではないことだ。Claude Codeが起動するとき、まずすべてのSkillの名前とDescriptionをスキャンする。
そして、ユーザーの現在の問題に基づいて、どのSkillをロードすべきか判断する。
だから、Descriptionに最も重要な情報は、「このSkillは何をするか」ではなく、「どんな状況でロードすべきか」だ。
Descriptionは、実は全体のSkillのルーティングを担っている。
現実の世界では、「PR管理ツールを呼び出して」と頼む人はほとんどいない。むしろ、「このPR、CIがまた落ちてるから見てほしい」などの方が多い。
だから、良いDescriptionは、ユーザーの意図をできるだけ正確に表現し、機能の羅列は避けるべきだ。
私自身、こんな簡単な方法でチェックできると思う。
Descriptionを書いたら、そのSkillを全部削除し、その行だけ残す。そして自分に問いかける：ユーザーの問題を見たとき、モデルはこのSkillをロードすべきタイミングを理解できるか。
できなければ、さらに改善の余地がある。
#05 Skillの管理と配布
もう一つ、Skillの管理についてだ。
一人でSkillを使う場合は、実はとても簡単だ。いくつかSkillを書いて、自分で管理し、自分でアップデートすれば良い。
しかし、多くのチームでは、次第に同じ問題に直面する。
Skillが数個から数十個、あるいは数百個に増えたとき、これらをどう管理し、どうアップデートし、どうチームに配るか。
Anthropicのこの点での経験は、非常に参考になる。
小規模なチームなら、Skillはコードリポジトリと連動させる。プロジェクト内の.claude/skillsディレクトリに置けば良い。みんなで同じSkillセットを共有し、同じ作業方法を使う。
しかし、Skillの数が増え続けると、新たな問題が出てくる。
Claude Codeの起動時、すべてのSkillの名前とDescriptionをスキャンし、どのSkillを呼び出すか判断する。Skillが増えれば増えるほど、ルーティングのコストは高くなる。
これが理由で、AnthropicはMarketplaceを始めたのだが、さらに面白いのは、そのMarketplaceの管理方法だ。
多くの企業は、この問題に直面すると、まず承認フローを作る。誰がSkillを書いたか申請させ、承認後に公式Skillライブラリに登録する。
私たちも以前やっていたが、非常に重い管理だった。
Anthropicの組織は、非常に軽やかだ。
新しいSkillはまず小さな範囲で展開し、同僚が自分でインストールして試用させる。
多くの人が使い始めて、実際に問題解決に役立つと判断されたら、その段階で正式なMarketplaceに登録する。
つまり、最初から価値の有無を議論するのではなく、実運用の中で検証し、多くの人に使われて初めて正式化する。そうして残ったSkillは、ほぼ確実にチームにとって必要なSkillになる。