Skills は、Claude Code で最も広く使われている拡張ポイントの 1 つになりました。柔軟で、作りやすく、配布も簡単です。しかし柔軟すぎるがゆえに、どう使うのが最善なのか分かりにくいという側面もあります。

本記事の著者 Thariq Shihipar は Anthropic の Claude Code チームのエンジニアで、Skills 機能の中核を推進した 1 人でもあります。この記事の価値は、Anthropic 内部チームによる実戦の総括であるという点にあります。Anthropic 内部で活用されている Skills はすでに数百個に上り、文中の分類体系や執筆テクニックは、こうした実際の内部実践から抽出・磨き上げられたものです。

Skills は単なる Markdown ファイルではない

「Skills は markdown ファイルにすぎない」という誤解を耳にすることがよくあります。しかし Skills の最も面白いところは、まさにテキストファイルだけではないという点です。Skills はフォルダであり、スクリプト、リソースファイル、データなどを含められますし、エージェントはそれらを発見し、探索し、利用できます。

Claude Code では、Skills は動的フック（hooks）の登録を含む豊富な設定オプションも備えています。Claude Code で特に面白い Skills は、こうした設定オプションとフォルダ構造を創造的に活用しているものが多い、というのが私たちの発見です。

Skills の 9 つのタイプ

すべての Skills を整理したところ、それらがいくつかの繰り返し現れるカテゴリに大別できることに気づきました。優れた Skills は 1 つのカテゴリにきれいに収まっており、混乱を招く Skills はたいてい複数にまたがっています。

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

あるライブラリ、コマンドラインツール、SDK を正しく使うための Skills です。内部ライブラリ向けにも、Claude Code がときどきミスをしがちな著名ライブラリ向けにも作れます。この種の Skills には、リファレンスとなるコードスニペットのフォルダと、Claude がコードを書くときに避けるべき落とし穴のリストが含まれていることが多いです。

例：

• billing-lib：内部の課金ライブラリで、境界ケースやハマりどころなど
• internal-platform-cli：内部 CLI ツールの各サブコマンドとその使用シーンの例
• frontend-design：Claude があなたのデザインシステムをよりよく理解できるようにする

2. プロダクト検証

コードが正常に動くかどうかをテスト・検証する方法を記述した Skills です。通常、Playwright や tmux などの外部ツールと組み合わせて検証を完了させます。

検証系の Skills は、Claude の出力の正しさを担保するうえで非常に有用です。エンジニア 1 人に 1 週間かけて、あなたの検証 Skills を徹底的に磨かせる価値があります。

例：

• signup-flow-driver：ヘッドレスブラウザでサインアップ→メール認証→オンボーディングのフローを走らせ、各ステップに状態アサーションのフックを差し込める
• checkout-verifier：Stripe のテストカードで決済 UI を駆動し、請求書が最終的に正しいステータスになったかを検証
• tmux-cli-driver：TTY を必要とするインタラクティブなコマンドラインテスト向け

3. データ取得と分析

あなたのデータやモニタリング体制につなぐ Skills です。この種の Skills には、クレデンシャル付きのデータ取得ライブラリ、特定のダッシュボード ID などに加え、よく使うワークフローやデータ取得方法の説明が含まれることがあります。

例：

• funnel-query：サインアップ→アクティベーション→課金のコンバージョンを見るには、どのイベントを紐付ける必要があるか？正規の user_id が本当に入っているあのテーブルも忘れずに
• cohort-compare：2 つのユーザーグループのリテンションやコンバージョン率を比較し、統計的に有意な差をマーキング
• grafana：データソースの UID、クラスター名、問題→ダッシュボードの対応表

4. 業務フローとチームの自動化

反復的なワークフローを 1 コマンドに自動化する Skills です。この種の Skills は指示自体はシンプルなことが多いのですが、他の Skills や MCP（Model Context Protocol）に依存する場合があります。

例：

• standup-post：タスクトラッカー、GitHub アクティビティ、過去の Slack メッセージを集約→整形されたスタンドアップ報告を生成
• create-ticket：schema の強制（有効な enum 値、必須フィールド）に加え、作成後のワークフローも規定
• weekly-recap：マージ済み PR + クローズ済みチケット + デプロイ記録→整形された週報

5. コードスキャフォールドとテンプレート

コードベース内の特定の機能について、ひな形となるボイラープレートコードを生成する Skills です。スキャフォールドに自然言語での要件が絡み、コードだけではカバーできない場合に特に有用です。

例：

• new-workflow：あなたのアノテーションを使って新しいサービス／ワークフロー／プロセッサを組み立てる
• new-migration：データベース移行ファイルのテンプレートと、よくあるハマりどころ
• create-app：内部アプリを新規作成し、認証、ロギング、デプロイ設定を事前構成

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

チーム内でコード品質基準を強制し、コードレビューを支援する Skills です。最大の信頼性を担保するために、決定論的なスクリプトやツールを含められます。

例：

• adversarial-review：まったく新しい視点のサブエージェントを生成して欠点を探させ、修正を実施し、反復する
• code-style：コードスタイルの強制、特に Claude がデフォルトで苦手なスタイル
• testing-practices：テストの書き方と、何をテストすべきかのガイダンス

7. CI/CD とデプロイ

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

例：

• babysit-pr：1 つの PR を監視→不安定な CI をリトライ→マージコンフリクトを解消→自動マージを有効化
• deploy-service：ビルド→スモークテスト→段階的トラフィック切り替えとエラー率の比較→指標が悪化したら自動ロールバック
• cherry-pick-prod：隔離されたワークツリー→cherry-pick→コンフリクト解消→テンプレートで PR 作成

8. 運用手順書

1 つの現象（Slack メッセージ、アラート、エラーパターンなど）を受け取り、複数ツールをまたぐ調査フローを案内し、最後に構造化レポートを生成する Skills です。

例：

• service-debugging：現象をツール→クエリパターンに対応付け、トラフィックの多いサービスをカバー
• oncall-runner：アラートを取得→よくある容疑者をチェック→調査結果を整形して出力
• log-correlator：1 つのリクエスト ID を与えると、通過しうるすべてのシステムから一致するログを取得

9. インフラ運用

日常のメンテナンスと運用操作を実行する Skills です。その一部は破壊的な操作を含むため、安全なガードレールが必要です。これらの Skills により、エンジニアは重要な操作の際にベストプラクティスに従いやすくなります。

例：

• cleanup-orphans：孤立した Pod/Volume を発見→Slack に投稿→観察期間を置く→ユーザー確認→連鎖的にクリーンアップ
• dependency-management：あなたの組織の依存ライブラリ承認ワークフロー
• cost-investigation：ストレージ／下り帯域のコストがなぜ突然跳ね上がったのか、具体的なバケットとクエリパターンつき

Skills を書く 8 のテクニック

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

Claude Code はあなたのコードベースをすでに非常によく理解していますし、Claude 自体もプログラミングが得意です。公開する Skill が主に知識を提供するものなら、重点を置くべきは Claude の常套的な考え方を打破できる情報のほうです。

たとえば Anthropic の frontend-design Skill は、Inter フォントや紫のグラデーションといった典型的な型をあえて避けさせています。

2. 落とし穴セクションを作る

どんな Skill でも最も情報量が多いのは落とし穴セクションです。こうしたセクションは、Claude がその Skill を使うなかで遭遇した典型的な失敗ポイントを、段階的に積み上げていくべきものです。理想的には、こうした落とし穴を記録し続ける形で Skill を継続的に更新していくとよいでしょう。

3. ファイルシステムと漸進的ディスクロージャーを活用する

Skill は 1 つの markdown ファイルではなく、フォルダです。ファイルシステム全体を、コンテキストエンジニアリングと漸進的ディスクロージャーの道具として扱うべきです。Skill にどんなファイルがあるかを Claude に伝えておけば、適切なタイミングでそれを読みに行きます。

最もシンプルな漸進的ディスクロージャーは、他の markdown ファイルへの参照を置くことです。たとえば、詳細な関数シグネチャや使用例を references/api.md に切り出せます。

4. Claude を縛りすぎない

Claude は通常、あなたの指示に従おうと努力します。Skills は再利用性が高いため、指示を書きすぎ具体的にしないよう注意が必要です。Claude に必要な情報を与えつつ、状況に応じて適応する柔軟性は残しましょう。

5. 初期セットアップをよく考える

一部の Skills では、初期セットアップのためにユーザーからコンテキストを提供してもらう必要があります。良いやり方は、そうした設定情報を Skill ディレクトリ以下の config.json ファイルに保存しておくことです。設定がまだ済んでいなければ、エージェントがユーザーに関連情報を尋ねます。

6. description フィールドはモデルのためのもの

Claude Code はセッションを開始するとき、利用可能なすべての Skills とその説明のリストを構築します。Claude はこのリストを走査して「このリクエストに該当する Skill はあるか？」を判断します。つまり description フィールドは要約ではなく、「いつこの Skill を発動すべきか」を記述するものなのです。

7. メモリとデータストア

一部の Skills は、内部にデータを保存することで、ある種のメモリを実現できます。最もシンプルな方法である追記専用のテキストログファイルや JSON ファイルでもいいですし、より複雑な方法として SQLite データベースなども使えます。

たとえば standup-post Skill は standups.log を保持し、書いたスタンドアップ報告をすべて記録できます。そうすれば次回の実行時に、Claude は自分の履歴を読み、昨日から今日にかけて何が変わったのかを把握できるのです。

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

Claude に与えられる最強の道具の 1 つがコードです。Claude にスクリプトとライブラリを提供し、その力を組み合わせとオーケストレーションに注ぎ込ませましょう。次に何をするかを決めることこそが本質で、ボイラープレートを再構成することではありません。

たとえばデータサイエンスの Skill に、イベントソースからデータを取得する関数ライブラリ一式を置いておけます。Claude はそうした機能を組み合わせるスクリプトをその場で生成し、より高度な分析をこなせるのです。

Skills の配布

Skills の最大の利点の 1 つは、チームの他のメンバーと共有できることです。

Skills の共有方法は 2 通りあります：

• Skills をコードリポジトリにコミットする（./.claude/skills 以下に置く）
• プラグインとして、Claude Code のプラグインマーケットを立ち上げ、ユーザーがプラグインをアップロード・インストールできるようにする

少数のリポジトリで協業する小さなチームなら、Skills をリポジトリにコミットするだけで十分です。ただし、コミットされた 1 つ 1 つの Skill がモデルのコンテキストに少しずつ負担を足します。規模が拡大したら、内部プラグインマーケットを使えば Skills を配布しつつ、チームメンバー自身がどれをインストールするかを決められるようになります。

Toolin 実測レビュー

向いている人：

• Claude Code で開発しているチーム
• 開発フローの標準化が必要な組織
• AI 支援プログラミングの効率を上げたい開発者

コアバリュー：

• チームの知識とベストプラクティスをコード化し、同じ落とし穴の繰り返しを防ぐ
• 検証系 Skills によって AI 生成コードの信頼性を向上
• 反復的なワークフローを自動化し、開発者の時間を解放
• チーム協業とナレッジ共有を支援

導入のすすめ：

1. 最も痛いところから始める：チーム最大のペインを解決する 1〜2 個の Skills をまず作る
2. 継続的に反復：Claude の実際の使用状況に応じて落とし穴を補い続ける
3. 共有の仕組みを作る：チームメンバーによる Skills の貢献と改善を奨励する
4. 効果を測定する：PreToolUse フックを使って Skills の利用状況を記録する

注意点：

• Skills は多ければよいわけではなく、1 つ 1 つがコンテキストを消費します
• description フィールドには機能の説明ではなく、発動条件を明確に書く
• 検証系 Skills は、より多くの時間をかけて磨く価値があります

Skills は AI エージェントにとって極めて強力で柔軟な道具ですが、この分野はまだ初期段階にあります。Skills を理解する最善の方法は、手を動かして作り始め、実験を重ね、自分にとって何が効くのかを見ることです。ほとんどの Skills は、最初は数行のテキストと 1 つの落とし穴にすぎません。みんなが Claude の新たな境界ケースを補い続けたからこそ、徐々に良くなっていったのです。