Claude Codeを作ったチームが、自分たちの職場でスキルをどう使っているかを公開しました。単に「こう作るといい」という話ではなく、数百のスキルを実践で動かしながら何がうまくいき、何がうまくいかないかをまとめたものです。執筆者はThariq Shihipar — Claude Codeチームのエンジニアで、「Claude Code is All You Need」で120万ビューを記録した人物です。
これは何?
AnthropicはClaude Codeを社内で開発しながら、同時に自分たちが最大のユーザーでもあります。9つのチーム — セキュリティ、法務、インフラ、フロントエンド、データなど — がそれぞれのスキルを作って活用しており、その数は数百に上ります。
今回公開されたのは大きく2つです。まず、Claude Code公式ドキュメントに追加されたBest PracticesとSkillsガイド。次に、ThariqがXで共有した社内運用の経験です。従来の33ページPDFガイドが「スキルをどう作るか」だったとすれば、これは「数百を実践で動かしてみたら、これが本当に大事だった」という話です。
核心のメッセージは明確です — スキルの成否は、作成前の設計でほぼ決まる。 コードを一行も書かずに、まずユースケースを3つ定義しなさい、ということです。
何が変わるのか?
従来の33ページガイドは「スキルとはこういうもので、こう作れ」というものでした。今回の公開はレベルが違います — 実践で何がうまくいき、何がうまくいかないか、そしてチーム規模でどう管理するかを扱います。
| 従来の33pガイド | 社内プレイブック（今回の公開） | |
|---|---|---|
| 焦点 | スキルの概念と作り方 | 数百を運用して学んだパターンとアンチパターン |
| 設計原則 | SKILL.mdフォーマットの説明 | ユースケース3つ先に → その後作成 |
| 品質管理 | 基本テストの言及 | トリガー/機能/パフォーマンス3段階検証体系 |
| チーム共有 | パスのみ言及 | Enterprise → Personal → Project 優先度体系 + プラグイン配布 |
| コンテキスト管理 | 簡略に言及 | character budget 2%ルール + 500行上限 + progressive disclosure |
| トリガー制御 | 基本説明 | Hookによる強制トリガー + disable-model-invocation分離 |
特に印象的なのが70%ルールです。Anthropic内部チームで共通して見られるパターンで — Claude Codeが実装作業の約70%を安定的に処理し、残り30%を人間が担うというものです。この30%こそがスキルの設計、検証ループ、エッジケース処理なんです。
始め方のポイント
- ユースケースを3つ先に定義する
スキルを作る前に、「誰が、何を言えば、どんな結果が出るべきか」を3つのシナリオで書いてみてください。Anthropicはこのステップを飛ばすとスキルの品質が劇的に落ちると言っています。シナリオ例：「PRレビューして」→ 3つの並列エージェントでセキュリティ/コード品質/効率性を検討 → 統合レポート - descriptionを精密に書く
Claudeはスキルを「progressive disclosure」でロードします。まずname + descriptionだけをシステムプロンプトに乗せ（約100トークン）、ユーザーのリクエストがマッチしたときにSKILL.mdの全文を読みます。 descriptionが曖昧だとトリガーされず、広すぎると的外れなタイミングで発動してしまいます。 - 検証ループをbodyに組み込む
Anthropicが最も強調するポイントです。実行 → 検証 → 修正 → 再検証のループをスキル本文にチェックリストとして入れてください。 たとえばコード生成スキルなら「生成後にlint実行 → テスト実行 → 失敗時に修正 → 再実行」を明示的に書く必要があります。 - 500行以下に維持する
SKILL.mdが長くなるとClaudeが指示を見落とします。詳細内容はreferences/フォルダに分離し、SKILL.mdには目次と核心的な指針だけ残してください。 参照ファイルが長い場合は先頭に目次を入れることで、Claudeがhead -100で読んだときに構造を把握できます。 - チームに共有する
スキルを.claude/skills/に入れてgitにコミットすれば、チーム全体で使えます。 個人用は~/.claude/skills/、組織全体はmanaged settingsで配布できます。優先度はEnterprise > Personal > Project の順です。
Anthropicが実践から学んだ5つの教訓
公式ドキュメントとThariqの共有から抽出した、数百のスキルを運用して得た核心的な教訓です。
教訓1：SKILL.md bodyに「When to Use」を書くな
descriptionでトリガー判断が終わり、bodyがロードされるタイミングです。bodyに「このスキルは〜のときに使います」と書いても、すでに発動した後に読まれるだけでコンテキストの無駄遣いです。bodyには「どう実行するか」だけを書いてください。
教訓2：副作用のあるスキルは必ず手動トリガーに
disable-model-invocation: trueを設定してください。デプロイ、コミット、Slackメッセージ送信のようなスキルは、Claudeが「コードが準備できたようなのでデプロイします」と自動実行してはいけません。
教訓3：スキルが多すぎると何も機能しない
Claudeはスキル一覧をコンテキストウィンドウの2%予算（最小16,000文字）内で管理します。スキルがこの予算を超えると、一部が完全に除外されます。/contextで確認できます。
教訓4：Hookでトリガー確率を上げる
スキルが呼ばれない最大の理由は、Claudeがdescriptionをマッチングできないことです。このときHookを使うと、ユーザーの入力にスキル推薦を直接付け加えられます — 「機能を実装するのを手伝って」に「CRITICAL SKILLS: session-management」を自動挿入する形です。
教訓5：context: forkでメインコンテキストを守る
リサーチやレビューのようなスキルはファイルを大量に読み、メインコンテキストを汚染します。context: forkを設定するとサブエージェントで隔離実行され、結果の要約だけが返ってきます。
実践スキル構成例
Anthropicが実際に使うパターンをベースに、チーム規模で効果的なスキル構成をまとめました。
| スキルタイプ | 例 | 主な設定 | 場所 |
|---|---|---|---|
| リファレンス（知識） | api-conventions, legacy-system-context | user-invocable: false（Claudeのみ呼び出し） | Project (.claude/skills/) |
| タスク（実行） | deploy, fix-issue, pr-summary | disable-model-invocation: true | Project (.claude/skills/) |
| 個人ワークフロー | explain-code, debug-session | デフォルト（自動＋手動どちらも） | Personal (~/.claude/skills/) |
| 組織標準 | code-review, security-audit | managed settingsで配布 | Enterprise |
ここでの核心は「リファレンススキル」と「タスクスキル」を明確に分けることです。 リファレンスはClaudeがコンテキストとして使う知識で、タスクはユーザーが明示的に実行するワークフローです。これを混在させると、スキルが的外れなタイミングで発動したり、必要なときに呼ばれなくなります。
以前のclaude-skills-guideポストとの違い
以前のポスト（Claude Skills 33ページガイド完全まとめ）はAnthropicが公開したPDFガイドを扱ったもので — スキルの概念、SKILL.mdの書き方、基本構成の説明が中心でした。このポストはその後に出た社内実践の経験を扱います。公式ドキュメントの更新 + ThariqのXスレッド + コミュニティ分析を総合したものです。
