Claude Code構築から得た教訓：スキルの活用方法【翻訳版】#

著者: Thariq Shihipar 原文: Lessons from Building Claude Code: How We Use Skills

> ガイド > 著者のThariq Shihipar（@trq212）は、AnthropicのClaude Codeチームのエンジニアであり、スキル機能のコア推進者の一人です。Anthropic入社前は、MITメディアラボの大学院生時代にオープンソースの学術出版プラットフォームPubPubを共同設立し、その後Y Combinator（W20期）に参加しました。Xでは、Claude Codeの新機能に関する生の経験や最新情報を頻繁に発信しています。 > > この記事の価値は、Anthropicチーム内部からの実践的なまとめである点にあります。Anthropic内部ではすでに数百のスキルが実際に活用されています。ここで紹介される分類体系や執筆のコツは、これらの実際の内部実践から抽出されたものです。もしあなたがすでにClaude Codeを使っているが、本格的にスキルを作成していないなら、この記事は体系的なアプローチを確立するのに役立ちます：どのような種類のスキルを作るべきか、どのように書くべきか、チーム内でどのように普及させるべきか。 > 引用ツイート > https://t.co/45C3gKydTK > https://x.com/i/web/status/2033949937936085378

スキルは、Claude Codeで最も広く使われている拡張ポイントの一つになりました。柔軟性が高く、作成が簡単で、配布もシンプルです。

しかし、まさにその柔軟性ゆえに、最適な使い方を知るのは難しいかもしれません。どのような種類のスキルを作る価値があるのでしょうか？良いスキルを書く秘訣は？いつ他の人と共有すべきでしょうか？

私たちはAnthropic内部でClaude Codeスキルを広範に使用しており、現在数百のスキルが実際に活用されています。ここでは、スキルを使って開発を加速させるために学んだ教訓を紹介します。

スキルとは？#

スキルに馴染みがない場合は、まずドキュメントまたは最新のAgent Skillsに関するSkilljarコースを確認することをお勧めします。この記事は、スキルの基本的な理解があることを前提としています。

「スキルは単なるマークダウンファイルだ」という誤解をよく耳にします。しかし、スキルについて最も興味深い点は、まさに単なるテキストファイルではないということです。スキルは、エージェントが発見、探索、使用できるスクリプト、リソースファイル、データなどを含むことができるフォルダです。

Claude Codeでは、スキルには豊富な設定オプションがあり、動的なフックの登録も含まれます。

私たちは、Claude Codeで最も興味深いスキルは、これらの設定オプションやフォルダ構造を創造的に活用しているものが多いことに気づきました。

すべてのスキルをレビューした後、それらは大まかにいくつかの繰り返し現れるカテゴリーに分類できることに気づきました。最良のスキルは、明確に一つのカテゴリーに適合しています。混乱を招くスキルは、しばしば複数のカテゴリーにまたがっています。これは決定的なリストではありませんが、チームにどのような種類のスキルが不足しているかを確認したい場合の良い出発点となります。

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

ライブラリ、コマンドラインツール、またはSDKを正しく使用するのに役立つスキル。内部ライブラリや、Claude Codeが時々間違える一般的なライブラリを対象にすることができます。これらのスキルには通常、参照用のコードスニペットのフォルダと、Claudeがコードを書く際に避けるべき落とし穴のリストが含まれます。

例:

billing-lib — 内部の請求ライブラリ：エッジケース、注意点など
internal-platform-cli — 内部CLIツールの各サブコマンドとその使用例
frontend-design — Claudeがデザインシステムをよりよく理解するのを助ける

2. 製品検証#

コードが正しく動作することをテストまたは検証する方法を説明するスキル。Playwright、tmuxなどの外部ツールと組み合わせて検証を完了することがよくあります。

検証スキルは、Claudeの出力の正確性を確保するのに非常に有用です。エンジニアが1週間かけて検証スキルを洗練させる価値があります。

出力プロセスのビデオをClaudeに記録させて実際に何をテストしたかを確認する技術や、各ステップでプログラムによる状態アサーションを強制する技術を検討してください。これらは通常、スキル内に様々なスクリプトを含めることで実装されます。

例:

signup-flow-driver — ヘッドレスブラウザでサインアップメール確認→オンボーディングフローを実行し、各ステップで状態アサーションを挿入するフックを含む
checkout-verifier — StripeテストカードでチェックアウトUIを操作し、請求書が正しい状態になることを確認
tmux-cli-driver — TTYを必要とする対話型コマンドラインインターフェースをテスト

3. データ取得 & 分析#

データと監視システムに接続するスキル。これらのスキルには、認証情報を含むデータ取得ライブラリ、特定のダッシュボードIDなどに加えて、一般的なワークフローやデータ取得方法の指示が含まれる場合があります。

例:

funnel-query — 「サインアップアクティベーション→有料変換を見るにはどのイベントを関連付ける必要があるか？」、および正規のuser_idが保存されている実際のテーブル
cohort-compare — 2つのユーザーグループ間のリテンションまたはコンバージョン率を比較し、統計的に有意な差をフラグ付け、コホート定義へのリンクを提供
grafana — データソースUID、クラスター名、問題ダッシュボードマッピングテーブル

4. ビジネスプロセス & チーム自動化#

繰り返しのワークフローを単一のコマンドに自動化するスキル。これらのスキルの指示は通常シンプルですが、他のスキルやMCP（Model Context Protocol）に依存する場合があります。これらのスキルでは、以前の実行結果をログファイルに保存することで、モデルが一貫性を維持し、以前の実行を振り返ることができます。

例:

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 — 新鮮な視点のサブエージェントを生成して細かい点を指摘させ、修正を実装し、問題が細かい指摘に退化するまで繰り返す [注：サブエージェントとは、Claude Codeがタスクを実行中に起動する別の独立したClaudeインスタンスのこと。ここでのアプローチは、このコードを見たことのない新しいインスタンスにコードレビューを行わせ、元のインスタンスの思考の慣性を避けることです。]
code-style — コードスタイルを強制、特にClaudeがデフォルトでうまく扱えないスタイル
testing-practices — テストの書き方と何をテストすべきかに関するガイダンス

7. CI/CD & デプロイメント#

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

例:

babysit-pr — PRを監視不安定なCIを再試行→マージコンフリクトを解決→自動マージを有効化
deploy-<service> — ビルドスモークテスト→エラーレート比較による段階的なトラフィックシフト→メトリクス悪化時の自動ロールバック
cherry-pick-prod — 分離されたワークツリーチェリーピック→コンフリクト解決→テンプレートを使用したPR作成

8. ランブック#

症状（例：Slackメッセージ、アラート、エラーシグネチャ）を受け取り、マルチツール調査プロセスを案内し、最終的に構造化されたレポートを生成するスキル。

例:

<service>-debugging — 症状をツールクエリパターンにマッピング、最もトラフィックの多いサービスをカバー
oncall-runner — アラートを取得一般的な疑わしい点をチェック→調査結論をフォーマット
log-correlator — リクエストIDが与えられると、通過した可能性のあるすべてのシステムから一致するログを取得

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

日常的なメンテナンスや運用タスクを実行するスキル—安全ガードレールを必要とする破壊的操作を含むものもあります。これらのスキルは、エンジニアが重要な操作を行う際にベストプラクティスに従いやすくします。

例:

<resource>-orphans — 孤立したPod/ボリュームを検出Slackに投稿→待機して観察→ユーザー確認→連鎖的なクリーンアップ
dependency-management — 組織の依存関係承認ワークフロー
cost-investigation — 「ストレージ/エグレスコストが急に増加したのはなぜ？」、特定のバケットとクエリパターンを含む

作成するスキルを決めたら、どのように書けばよいでしょうか？以下に、私たちがまとめたベストプラクティスとコツを紹介します。

最近ではSkill Creatorもリリースされ、Claude Codeでのスキル作成がさらに簡単になりました。

自明なことは述べない#

Claude Codeはすでにあなたのコードベースをよく理解しており、Claude自体もプログラミングに熟練しており、多くのデフォルトの意見を持っています。もしあなたのスキルが主に知識を提供するものであれば、Claudeの従来の思考パターンを破る情報に焦点を当ててください。

フロントエンドデザインスキルは素晴らしい例です—これはAnthropicのエンジニアがユーザーとの繰り返しのイテレーションを通じて構築し、Claudeのデザインセンスを向上させ、特にInterフォントや紫色のグラデーションなどの典型的なトロープを避けるようにしました。

落とし穴セクションを作成する#

あらゆるスキルで最も有益な部分は、落とし穴セクションです。これらのセクションは、Claudeがあなたのスキルを使用する際に遭遇する一般的な失敗点に基づいて徐々に構築されるべきです。理想的には、これらの落とし穴を文書化するためにスキルを継続的に更新していくことになります。

ファイルシステムと段階的開示を活用する#

前述のように、スキルは単なるマークダウンファイルではなく、フォルダです。コンテキストエンジニアリングと段階的開示のツールとして、ファイルシステム全体を扱うべきです。Claudeにスキル内のファイルを伝えると、適切な時にそれらを読みます。[注：コンテキストエンジニアリングは、2025年にAndrej Karpathyらによって提唱・普及した概念で、大規模言語モデルに入力するコンテキスト情報を注意深く設計・管理して出力品質を最大化することを指します。段階的開示はUIデザインから借用したもので、すべての情報を一度にモデルにダンプするのではなく、必要に応じて読み込ませることで、コンテキストウィンドウのスペースを節約します。]

段階的開示の最も単純な形式は、Claudeが使用するための他のマークダウンファイルを指し示すことです。例えば、詳細な関数シグネチャと使用例をreferences/api.mdに分割できます。

別の例：最終出力がマークダウンファイルの場合、コピー用のテンプレートファイルをassets/に配置できます。

Claudeがより効率的に作業できるように、references、scripts、examplesなどのフォルダを持つことができます。

Claudeを制約しすぎない#

Claudeは通常、あなたの指示に従おうと懸命に努力します。また、スキルは非常に再利用性が高いため、指示があまりにも具体的に書きすぎないように注意する必要があります。Claudeに必要な情報を与えつつ、特定の状況に適応する柔軟性を残してください。例：

初期設定を考慮する#

一部のスキルでは、初期設定のためにユーザーがコンテキストを提供する必要がある場合があります。例えば、スタンドアップ更新をSlackに投稿するスキルを作成する場合、Claudeに最初にどのSlackチャンネルに投稿するかをユーザーに尋ねさせたいかもしれません。

良いプラクティスは、上記の例のように、この設定情報をスキルディレクトリ内のconfig.jsonファイルに保存することです。設定がまだセットアップされていない場合、エージェントはユーザーに関連情報を尋ねます。

エージェントに構造化された複数選択の質問をユーザーに提示させたい場合は、ClaudeにAskUserQuestionツールを使用させることができます。

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

Claude Codeがセッションを開始するとき、利用可能なすべてのスキルとその説明のリストを構築します。Claudeはこのリストをスキャンして「このリクエストに対応するスキルはあるか？」を判断します。したがって、descriptionフィールドは要約ではなく、このスキルがいつトリガーされるべきかを説明するものです。[注：このアドバイ