Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Claude Code構築から得られた教訓：スキルの活用方法

Anthropic社内で何百ものスキルを構築・スケールさせる中で学んだこと。

スキルは、Claude Codeにおいて最もよく使われる拡張ポイントの1つとなっています。柔軟で、作成しやすく、配布もしやすいのが特徴です。

しかし、この柔軟性ゆえに、どのような方法が最適なのかを見極めるのが難しくなることもあります。どのようなスキルを作る価値があるのか？ スキルはどのように構成すべきか？ いつ他のメンバーと共有すべきか？

Anthropicでは、Claude Codeのスキルを幅広く活用しており、現在何百ものスキルがアクティブに使用されています。開発を加速させるためにスキルをどのように活用しているか、私たちが得た教訓を紹介します。

スキルとは何か？

スキルとは、エージェントがより正確かつ効率的にタスクを実行できるように、発見して利用できる「指示、スクリプト、リソースを含むフォルダ」のことです。この記事では、スキルの基本について理解していることを前提としています。初めての方は、まずSkilljarの「Introduction to agent skills course（エージェントスキル入門コース）」から始めてください。

スキルについてよくある誤解は、「単なるMarkdownファイルである」というものです。実際には、エージェントが探索し操作できるスクリプト、アセット、データなどを含む「フォルダ」です。

Claude Codeにおけるスキルには、動的なフックの登録など、非常に多様な設定オプションも用意されています。

Claude Codeで最も効果的なスキルのいくつかは、これらの設定オプションやフォルダ構造を効果的に使用していることが分かっています。

スキルの種類

Anthropicの社内スキルをすべて分類したところ、9つのカテゴリに分類できることが分かりました。優れたスキルはどれか1つのカテゴリに綺麗に収まります。多くのことをやろうとしすぎるスキルは、複数のカテゴリにまたがってしまい、エージェントを混乱させます。これは決定版のリストではありませんが、自身のスキルライブラリの不足部分を特定するための有用なフレームワークです。

Claude Codeのチームが社内スキルを分類したところ、9つの異なるカテゴリに分けられることが分かりました。

1. ライブラリとAPIリファレンス

これらは、ライブラリ、CLI、またはSDKの正しい使用方法を説明するスキルです。社内ライブラリ用と、Claude Codeが時折処理に苦労する一般的なライブラリ用の両方が考えられます。これらのスキルには、参照用コードスニペットのフォルダや、Claudeがスクリプトを書く際に避けるべき注意点（gotchas）のリストが含まれていることがよくあります。

例：

  • billing-lib — 社内の請求ライブラリ：エッジケース、陥りやすい罠など。
  • internal-platform-cli — 社内CLIラッパーのすべてのサブコマンドと、それらをいつ使用するかの例。
  • sandbox-proxy — 開発作業用の組織の送信ゲートウェイの設定：どのホストが到達可能か、「接続拒否」エラーのデバッグ方法、許可リストへのエントリ追加方法。

2. 製品の検証

これらは、コードが動作していることをテストまたは検証する方法を記述したスキルです。検証のために、Playwright、tmux、またはその他の外部ツールと組み合わされることがよくあります。

検証スキルは、Anthropic社内においてClaudeの出力品質に最も測定可能な影響を与えました。エンジニアが1週間かけて検証スキルを優れたものにする価値は十分にあります。

Claudeに出力結果の動画を録画させて何をテストしたかを正確に確認できるようにしたり、各ステップで状態のプログラム的なアサーションを強制したりするなどの手法を検討してください。これらは通常、スキルにさまざまなスクリプトを含めることで実現されます。

例：

  • signup-flow-driver — ヘッドレズブラウザで「サインアップ → メール確認 → オンボーディング」を実行し、各ステップで状態をアサートするためのフックを持つ。
  • checkout-verifier — Stripeのテストカードを使用してチェックアウトUIを操作し、インボイスが実際に正しい状態で作成されたかを検証する。
  • tmux-cli-driver — 検証対象にTTYが必要なインタラクティブなCLIテスト用。

3. データの取得と分析

これらは、データおよび監視スタックに接続するスキルです。これらのスキルには、認証情報を使用してデータを取得するライブラリや、特定のダッシュボードIDなどが含まれるほか、一般的なワークフローやデータ取得方法に関する指示が含まれます。

例：

  • funnel-query — 「サインアップ → アクティベーション → 有料化」を確認するためにどのイベントを結合するか、および標準の user_id を実際に持つテーブルの情報。
  • cohort-compare — 2つのコホートのリテンションまたはコンバージョンを比較し、統計的に有意な差をフラグ付けし、セグメント定義にリンクする。
  • grafana — データソースUID、クラスター名、問題とダッシュボードのルックアップテーブル。
  • datadog — フィールド参照（@request_id と trace_id）、サービスリスト、メトリクスのプレフィックス規約。

4. ビジネスプロセスとチームの自動化

これらは、繰り返しの多いワークフローを1つのコマンドに自動化するスキルです。これらのスキルは通常、非常にシンプルな指示ですが、他のスキルやMCPに複雑に依存している場合があります。これらのスキルでは、以前の結果をログファイルに保存しておくことで、モデルが一貫性を保ち、ワークフローの以前の実行結果を振り返るのに役立ちます。

例：

  • standup-post — チケットトラッカー、GitHubのアクティビティ、前回のSlackの内容を集計し、差分のみをフォーマットされたスタンドアップとして投稿する。
  • create-<ticket-system>-ticket — スキーマ（有効な列挙値、必須フィールド）を強制し、作成後のワークフロー（レビュー担当者への通知、Slackでのリンク）を実行する。
  • weekly-recap — マージされたPR ＋ クローズされたチケット ＋ デプロイ → フォーマットされた週次振り返り投稿を作成する。

5. コードの足場（スキャフォールディング）とテンプレート

これらは、コードベース内の特定の機能に対してフレームワークのボイラープレートを生成するスキルです。構成可能なスクリプトとこれらのスキルを組み合わせることができます。コードだけで完全にカバーできない、自然言語の要件が足場にある場合に特に役立ちます。

例：

  • new-<framework>-workflow — アノテーションを付与して、新しいサービス/ワークフロー/ハンドラーの足場を作成する。
  • new-migration — マイグレーションファイルのテンプレートと、よくある注意点。
  • create-app — 認証、ロギング、デプロイ設定があらかじめ組み込まれた、新しい社内アプリを作成する。

6. コード品質とレビュー

これらは、組織内のコード品質を強制し、コードのレビューを支援するスキルです。堅牢性を最大化するために、決定論的なスクリプトやツールを含めることができます。これらのスキルは、フックの一部として、またはGitHub Actionの内部で自動的に実行するとよいでしょう。

  • adversarial-review — 客観的な視点を持つサブエージェントを立ち上げて批判させ、修正を実装し、指摘事項が些細なもの（nitpick）になるまで繰り返す。
  • code-style — コードスタイル、特にClaudeがデフォルトではうまく対応できないスタイルを強制する。
  • testing-practices — テストの書き方やテストすべき内容に関する指示。

7. CI/CDとデプロイ

これらは、コードベース内でのコードの取得、プッシュ、デプロイを支援するスキルです。これらのスキルは、データを収集するために他のスキルを参照することがあります。

例：

  • babysit-pr — PRを監視 → 不安定なCIを再試行 → マージコンフリクトを解消 → 自動マージを有効化する。
  • deploy-<service> — ビルド → スモークテスト → エラー率比較を伴う段階的なトラフィックロールアウト → 退行（デグレード）発生時の自動ロールバック。
  • cherry-pick-prod — 隔離された作業ツリー（worktree） → チェリーピック → コンフリクト解消 → テンプレートを使用したPR作成。

8. ランブック

これらは、兆候（Slackのスレッド、アラート、エラーの特徴など）を受け取り、複数のツールを使用した調査手順を実行し、構造化されたレポートを作成するスキルです。

例：

  • <service>-debugging — 最もトラフィックの多いサービスについて、兆候 → ツール → クエリパターンの対応付けを行う。
  • oncall-runner — アートを取得 → よくある原因を確認 → 調査結果をフォーマットする。
  • log-correlator — リクエストIDを指定すると、それに関わった可能性のあるすべてのシステムから一致するログを抽出する。

9. インフラストラクチャの運用

これらは、日常的なメンテナンスや運用手順を実行するスキルです。一部には、ガードレールを設けることで恩恵を受ける破壊的なアクションも含まれます。これにより、エンジニアが重要な運用においてベストプラクティスに従いやすくなります。

例：

  • <resource>-orphans — 孤立したPod/ボリュームを検出 → Slackに投稿 → 冷却期間 → ユーザーが確認 → 段階的なクリーンアップ。
  • dependency-management — 組織の依存関係の承認ワークフロー。
  • cost-investigation — 「なぜストレージ/送信料金が急増したのか」を特定のバケットやクエリパターンで調査する。

スキル作成のヒント

作成するスキルを決めたら、どのように書けばよいでしょうか？ ここでは、Claude Codeチームが推奨するスキルの作成におけるベストプラクティス、ヒント、テクニックを紹介します。

当たり前のことは書かない

Claudeはすでにコードの書き方を知っており、コードベースを読むこともできます。Claudeがデフォルトで行うことを単に再掲するだけのスキルは、価値を付加せずにコンテキストを増やすだけです。主に知識に関するスキルを公開する場合は、Claudeを通常の思考パターンから脱却させる情報に焦点を当ててください。

frontend design（フロントエンドデザイン）のスキルは素晴らしい例です。これは、Anthropicのエンジニアが顧客と協力して、Interフォントや紫のグラデーションといった典型的なパターンを避け、Claudeのデザインセンスを向上させるために繰り返し改善して構築したものです。

注意点（Gotchas）セクションを作る

スキルの中で最もシグナルが高いコンテンツは、「Gotchas（注意点）」セクションです。このセクションは、Claudeがスキルを使用する際に遭遇した一般的な失敗事例を蓄積して作成されるべきです。理想的には、これらの注意点を反映するために、時間をかけてスキルを更新していくとよいでしょう。

例えば：

「subscriptions テーブルは追加専用です。必要な行は、最新の created_at ではなく、最もバージョンが高い行です。」 「このフィールドは、APIゲートウェイでは @request_id、請求サービスでは trace_id と呼ばれていますが、同じ値です。」 「ステージング環境では、Stripeのウェブフックが実際には処理されていなくても200を返します。実際の状態を確認するには payment_events をチェックしてください。」

ファイルシステムと段階的開示（Progressive Disclosure）の活用

SKILL.mdファイルは、特定の状況でClaudeが参照できる他のいくつかのファイルを指し示します。例えば、ジョブが保留中の場合は、stuck-jobs.mdを参照するようにします。

前述のように、スキルは単なるMarkdownファイルではなく「フォルダ」です。ファイルシステム全体を、コンテキストエンジニアリングおよび段階的開示の一形態として捉えるべきです。スキル内にどのようなファイルがあるかをClaudeに伝えれば、Claudeは適切なタイミングでそれらを読み込みます。

最もシンプルな段階的開示の方法は、Claudeが使用できる他のMarkdownファイルを指し示すことです。例えば、詳細な関数シグネチャや使用例を references/api.md に分割することができます。

別の例として、最終的な出力がMarkdownファイルである場合、コピーして使用できるように assets/ にテンプレートファイルを含めておくことが挙げられます。

参照、スクリプト、例などのフォルダを用意することで、Claudeはより効果的に機能します。

Claudeの行動を制限（線路敷設）しすぎない

Claudeは通常、指示に忠実に従おうとします。スキルは再利用性が高いため、指示を細かく指定しすぎないように注意する必要があります。Claudeに必要な情報を与えつつ、状況に応じて適応できる柔軟性を持たせてください。

例えば：

セットアップについて十分に考える

上記のスキルは、設定にSlackチャンネルが含まれていない場合にユーザーに問いかけるように書かれています。

一部のスキルは、ユーザーからのコンテキストを使用してセットアップする必要がある場合があります。例えば、スタンドアップをSlackに投稿するスキルを作成する場合、どのSlackチャンネルに投稿するかをClaudeがユーザーに尋ねるようにしたい場合があります。

これを実現する優れたパターンは、上記の例のように、スキルのディレクトリ内にある config.json ファイルにこのセットアップ情報を保存することです。設定が完了していない場合、エージェントはユーザーに情報を求めることができます。

エージェントに構造化された選択式の質問を提示させたい場合は、Claudeに AskUserQuestion ツールを使用するように指示できます。

説明文は人間ではなくモデル向けに書く

Claude Codeがセッションを開始すると、利用可能なすべてのスキルとその説明文のリストを構築します。このリストは、Claudeが「この要求に対応するスキルはあるか？」を判断するためにスキャンするものです。つまり、説明（description）フィールドは概要ではなく、「いつこのスキルを起動すべきか」の説明になります。

説明文に「babysit（子守り）」のようなスキルのトリガーとなる言葉を含めておくと効果的です。

‍

Claudeの記憶を助ける

このテキストログファイルは、Claudeが「Sarahの認証PRをレビューした」などの過去のイベントを思い出すのに役立ちます。

一部のスキルは、内部にデータを保存することで一種の「記憶」を持たせることができます。追加専用のテキストログファイルやJSONファイルのようなシンプルなものから、SQLiteデータベースのような複雑なものまで、何にでもデータを保存できます。

例えば、standup-post スキルは、自身が作成したすべての投稿を standups.log に保持しておくことができます。これにより、次回実行時にClaudeは自身の履歴を読み込み、昨日から何が変更されたかを把握できます。

環境変数 ${CLAUDE_PLUGIN_DATA} を使用して、データを保存できる安定したディレクトリを取得できます。スキルのデータ永続化に関する詳細はこちらを参照してください：https://code.claude.com/docs/en/plugins-reference#persistent-data-directory

スクリプトの保存とコード生成

Claudeに与えることができる最も強力なツールの1つは「コード」です。スクリプトやライブラリを与えることで、Claudeはボイラープレートを再構築するのではなく、次に何をすべきかを決定する構成作業にターンを費やすことができます。

例えば、data-science スキルにおいて、イベントソースからデータを取得する関数のライブラリがあるとします。Claudeに複雑な分析を行わせるために、以下のようなヘルパー関数群を提供することができます。

これにより、Claudeは「火曜日に何が起きたか？」といったプロンプトに対して、これらの機能をその場でスクリプトを生成して組み合わせ、より高度な分析を行うことができます。

オンデマンドフックの利用

スキルには、そのスキルが呼び出されたときにのみアクティブになり、セッション期間中のみ持続するフックを含めることができます。常に実行したくはないが、特定の状況では非常に役立つ、よりこだわりのあるフックにこれを使用してください。

例えば：

  • /careful — Bashの PreToolUse マッチャーを介して rm -rf、DROP TABLE、force-push、kubectl delete をブロックします。本番環境を触っていると分かっているときにだけ有効にしたいもので、常にオンになっているとストレスになります。
  • /freeze — 特定のディレクトリ以外での編集/書き込みをすべてブロックします。デバッグ中に「ログを追加したいだけなのに、無関係なコードを誤って『修正』してしまう」のを防ぎのに役立ちます。

スキルの配布

スキルの最大のメリットの1つは、チームの他のメンバーと共有できることです。

スキルを他の人と共有する方法は2つあります。

  • リポジトリにスキルをコミットする（./.claude/skills 以下）
  • プラグインを作成し、ユーザーがプラグインをアップロードしてインストールできるClaude Codeプラグインマーケットプレイスを用意する（詳細はドキュメントを参照）

比較的少ないリポジトリで作業する小規模なチームでは、リポジトリにスキルをコミットする方法がうまく機能します。ただし、コミットされるスキルが増えるたびに、モデルのコンテキストが少しずつ増加します。規模が大きくなるにつれて、社内プラグインマーケットプレイスを導入することで、チームメンバーがインストールするスキルを選択できるようになり、セットアップフローを含めることも可能になります。

スキルマーケットプレイスの運営

どのスキルをマーケットプレイスに登録するかをどのように決定し、人々はどのようにそれらを提出するのでしょうか？

Anthropicでは、中央集権的なチームが決定するのではなく、最も有用なスキルを有機的に見つけ出すようにしています。誰かが試してほしいスキルを作った場合、GitHubのサンドボックスフォルダにアップロードし、Slackなどのフォーラムで他のメンバーに知らせます。

スキルが広く使われるようになったら（移行するかどうかはスキルの所有者が決定します）、PRを作成してマーケットプレイスに移動させます。

スキルの組み合わせ

お互いに依存するスキルを作成したい場合があります。例えば、ファイルをアップロードする「ファイルアップロードスキル」と、CSVを作成してアップロードする「CSV生成スキル」があるとします。このような依存関係管理は、まだマーケットプレイスやスキルにネイティブには組み込まれていませんが、他のスキルを名前で参照するだけで、インストールされていればモデルがそれらを呼び出します。

スキルの測定

スキルの利用状況を把握するために、社内でのスキルの使用状況をログに記録できる PreToolUse フックを使用しています（サンプルコードはこちら）。これにより、人気のスキルや、想定よりも起動回数が少ないスキルを特定することができます。

はじめに

スキルのベストプラクティスは現在も進化しています。私たちの優れたスキルのほとんどは、数行のコードと1つの注意点（gotcha）から始まり、Claudeが新たなエッジケースに遭遇するたびに人々が追加を繰り返すことで洗練されていきました。

スキルを理解する最善の方法は、まず作成し、実験し、何が自分に合うかを確認することです。

この記事は、AnthropicでClaude Codeの開発に取り組むテクニカルスタッフのメンバー、Thariq Shihiparによって執筆されました。