Claude Code構築の経験：私たちがSkillsをどのように活用しているか

Claude Code の構築経験：Skills の活用方法

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

本文の著者 Thariq Shihipar（@trq212）は、Anthropic の Claude Code チームに所属するエンジニアであり、Skills 機能の中核を担う推進者の一人です。Anthropic 入社前には MIT Media Lab で修士課程在籍中にオープンソースの学術出版プラットフォーム「PubPub」を共同設立し、その後 Y Combinator（W20 バッチ）に参加しました。X では Claude Code の実用的な使用経験や新機能に関する情報を頻繁に共有しています。

この記事の価値は、Anthropic 内部チームによる実践的な総括である点にあります。Anthropic 社内では現在数百個の Skills が活発に利用されており、本稿で示される分類体系や作成テクニックは、これら実際の社内運用から抽出されたものです。

すでに Claude Code を使用しているが、Skills について体系的に取り組んでいない場合、この記事は「どのような種類の Skills を作るか」「どのように記述するか」「チーム内でどう普及させるか」という点において、システム化された思考の枠組みを提供します。

Skills は、Claude Code において最も広く利用されている拡張ポイント（extension points）の一つとなっています。それらは柔軟で、作成も容易であり、配布も簡単です。

しかし、その柔軟さゆえに「どのように使うのが最善か」を判断するのは困難です。どのような種類の Skills に価値があるのか？優れた Skill を作成する秘訣は何か？いつ他者と共有すべきなのか？

Anthropic 社内では Claude Code の Skills（技能拡張）を大量に活用しており、現在数百個が活発に使用されています。以下は、Skills を活用して開発を加速させる過程で得られた経験則です。

Skills についてまだ詳しくない場合は、まず公式ドキュメントや最新の Skilljar で提供されている「Agent Skills」コースをご覧ください。本稿では、すでに Skills に関する基本的な知識があると仮定しています。

よくある誤解として、「Skills は単なる markdown ファイルに過ぎない」という考えがありますが、Skills の最も興味深い点は、それらがテキストファイルではないことにあります。Skills はフォルダであり、スクリプトやリソースファイル、データなどを格納できます。エージェントはこれらのコンテンツを発見し、探索し、利用することが可能です。

Claude Code において、Skills は動的フック（hooks）の登録など、豊富な設定オプションを備えています。

私たちが発見したのは、Claude Code において最も興味深い Skills の多くが、これらの設定オプションやフォルダ構造を創造的に活用しているという点です。

すべての Skills を整理した結果、それらは大まかにいくつかの反復出現するカテゴリに分類できることがわかりました。優れた Skills は明確に一つのカテゴリに属しており、混乱を招く Skills は複数のカテゴリにまたがっている傾向があります。これは究極のリストではありませんが、チーム内で不足している種類の Skills がないか確認するための良い指針となります。

特定のライブラリ、コマンドラインツール、または SDK を正しく使用するためのサポートを提供する Skills です。これらは内部ライブラリ向けにも、Claude Code が時々誤りを犯す一般的なライブラリ向けにも作成できます。此类 Skills には通常、参考となるコードスニペットを格納したフォルダと、Claude がコードを書く際に避けるべき注意点（gotchas）のリストが含まれます。

billing-lib — あなたの内部請求処理ライブラリ：境界ケースや、よくある落とし穴（footguns）など

internal-platform-cli — 内部 CLI ツールの各サブコマンドとその使用例

frontend-design — Claude にあなたのデザインシステムをより深く理解させるためのスキル

コードが正常に動作しているかどうかをテストまたは検証する方法を記述するスキル。通常、Playwright や tmux などの外部ツールを組み合わせて検証を行います。

検証用スキルは、Claude の出力の正しさを保証するために非常に有用です。エンジニアに週単位で時間を割いて、検証スキルの磨き上げを任せる価値があります。

例えば、Claude に実行プロセスの動画を録画させて、実際に何をテストしたかを確認できるようにするといった工夫も考えられます。あるいは、各ステップでプログラム的な状態アサーション（state assertion）を強制することも有効です。これらは通常、スキル内に各種スクリプトを含めることで実現されます。

signup-flow-driver — ヘッドレスブラウザ上で登録→メール検証→オンボーディングフローを完走させ、各ステップに状態アサーションのフックを挿入可能にするドライバー

checkout-verifier — Stripe のテストカードを使用してチェックアウト UI を駆動し、最終的にインボイスが正しいステータスに至ったかを検証するツール

tmux-cli-driver — TTY が必要な対話型コマンドラインテスト専用のドライバー

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

funnel-query — 「登録→アクティベーション→課金へのコンバージョンを見るにはどのイベントを紐付ける必要があるか？」という問いに対し、正規の user_id が格納されている実際のテーブルを指し示すスキル

cohort-compare — 2 つのユーザーセグメント間のリテンション率や転換率を比較し、統計的に有意な差異をマーク付け、セグメント定義へのリンクを提供する機能

grafana — データソース UID、クラスター名、問題からダッシュボードまでの対応表を管理するスキル

反復的なワークフローを単一のコマンドに自動化するスキル。これらのスキルは通常、指示がシンプルですが、他のスキルや MCP（Model Context Protocol：モデルコンテキストプロトコル）に依存することがあります。此类スキルでは、過去の執行結果をログファイルに保存しておくことで、モデルの一貫性を保ち、過去の執行状況を振り返ることを支援できます。

standup-post — タスクトラッカー、GitHub の活動履歴、および以前の Slack メッセージを統合し、フォーマットされたスタンドアップ報告を生成する機能。変更点のみ（delta-only）を報告します。

create--ticket — スキーマの強制（有効な列挙値と必須フィールド）に加え、作成後のワークフロー（レビュアーへの通知、Slack でのリンク送信）を実行します。

weekly-recap — マージされた PR、クローズされたチケット、デプロイ記録を統合し、フォーマットされた週次レポートを生成します。

コードベース内の特定機能に対してフレームワークのボイラープレート（boilerplate：雛形コード）を生成するスキル。これらのスキルはスクリプトと組み合わせて使用できます。あなたのスケフォールディング（scaffolding：骨組み作成）に自然言語での要件があり、コードのみではカバーしきれない場合に、この種のスキルが特に有用です。

new--workflow — アノテーションを用いて新しいサービス/ワークフロー/プロセッサを構築します。

new-migration — データベースマイグレーションファイルのテンプレートと、よくある失敗ポイント（pitfalls）を記載します。

create-app — 内部アプリケーションの新規作成。認証、ログ、デプロイ設定が事前にプロビジョニングされた状態で提供されます。

チーム内でコード品質基準を実行し、コードレビューを支援するスキル。最大限の信頼性を確保するための決定論的なスクリプトやツールを含めることができます。これらのスキルはフックの一部として自動的に実行するか、GitHub Actions 内で実行することを検討してください。

adversarial-review — 生成一个全新视角的子智能体来挑刺，实施修复，反复迭代直到发现的问题退化为吹毛求疵【注：子智能体（subagent）是指 Claude Code 在执行任务时启动的另一个独立 Claude 实例。这里的做法是让一个“没见过这段代码”的新实例来做代码审查，避免原实例的思维惯性。】

code-style — 强制执行代码风格，特别是那些 Claude 默认做不好的风格

testing-practices — 关于如何写测试以及测试什么的指导

帮你拉取、推送和部署代码的 Skills。这类 Skills 可能会引用其他 Skills 来收集数据。

babysit-pr — 监控一个 PR→重试不稳定的 CI→解决合并冲突→启用自动合并

deploy- — 构建→冒烟测试→渐进式流量切换并对比错误率→指标恶化时自动回滚

cherry-pick-prod — 隔离的工作树（worktree）→cherry-pick→解决冲突→用模板创建 PR

接收一个现象（比如一条 Slack 消息、一条告警或者一个错误特征），引导你走完多工具排查流程，最后生成结构化报告的 Skills。

-debugging — 把现象对应到工具→查询模式，覆盖你流量最大的服务

oncall-runner — 拉取告警→检查常见嫌疑→格式化输出排查结论

log-correlator — 给定一个请求 ID，从所有可能经过的系统中拉取匹配的日志

执行日常维护和运维操作的 Skills——其中一些涉及破坏性操作，需要安全护栏。这些 Skills 让工程师在执行关键操作时更容易遵循最佳实践。

-orphans — 找到孤立的 Pod/Volume→发到 Slack→等待观察→用户确认→级联清理

dependency-management — 你所在组织的依赖审批工作流

cost-investigation — “我们的存储/出口带宽费用为什么突然涨了”，附带具体的存储桶和查询模式

确定了要做什么 Skill 之后，怎么写呢？以下是我们总结的一些最佳实践和技巧。

我们最近还发布了 Skill Creator，让在 Claude Code 中创建 Skills 变得更加简单。

Claude Code 对你的代码库已经非常了解，Claude 本身对编程也很在行，包括很多默认的观点。如果你发布的 Skill 主要是提供知识，那就把重点放在能打破 Claude 常规思维模式的信息上。

frontend design 这个 Skill 就是一个很好的例子——它是 Anthropic 的一位工程师通过与用户反复迭代、改进 Claude 的设计品味而构建的，专门避免那些典型的套路，比如 Inter 字体和紫色渐变。

任何 Skill 中信息量最大的部分就是踩坑点章节。这些章节应该根据 Claude 在使用你的 Skill 时遇到的常见失败点逐步积累起来。理想情况下，你会持续更新 Skill 来记录这些踩坑点。

前述の通り、Skill（スキル）は単なる Markdown ファイルではなく、一つのフォルダです。あなたはファイルシステム全体を、コンテキストエンジニアリング（Context Engineering）と漸進的開示（progressive disclosure）のツールとして扱うべきです。Claude にあなたの Skill 内にどのようなファイルがあるかを伝えることで、必要な時にそれらを読み取らせることができます。【注：コンテキストエンジニアリング（Context Engineering）は 2025 年に Andrej Karpathy 氏らによって提唱され広まった概念で、大規模言語モデルに与える入力情報の文脈を綿密に設計・管理し、モデルの出力品質を最大化するものです。漸進的開示（progressive disclosure）は UI デザインからの借用された概念であり、一度にすべての情報をモデルに詰め込むのではなく、必要な時に読み取らせることで、コンテキストウィンドウのスペースを節約する手法です。】

最もシンプルな漸進的開示の形式は、Claude に使用させる他の Markdown ファイルへの参照です。例えば、詳細な関数シグネチャや使用例を references/api.md といったファイルに分割して保存できます。

別の例として、最終的な出力が Markdown ファイルになる場合、assets/ フォルダ内にコピー用のテンプレートファイルを配置することができます。

Claude がより効率的に作業できるよう、リファレンス資料、スクリプト、サンプルなどを格納するフォルダを設けることも可能です。

Claude を過度に制限しないこと

Claude は通常、あなたの指示に従おうと努めますが、Skill の再利用性が高いことを考慮し、指示をあまりにも具体的に書きすぎないよう注意が必要です。Claude に必要な情報を提供しつつ、具体的な状況への適応のための柔軟性は残しておきましょう。例えば：

一部の Skill では、初期設定を完了させるためにユーザーからの文脈情報が必要になる場合があります。例えば、スタンドアップミーティングの内容を Slack に投稿する Skill を作成した場合、Claude にはまずどの Slack チャンネルに送信するかをユーザーに尋ねてほしいと考えるかもしれません。

良いプラクティスとして、上記の例のように、設定情報を Skill ディレクトリ内の config.json ファイルに保存します。まだ設定が完了していない場合、エージェントはユーザーに対して関連情報の入力を求めます。

エージェントにユーザーに対して構造化された多肢選択式の問題を表示させたい場合は、Claude に AskUserQuestion ツールを使用させることができます。

description フィールドはモデル向けです

Claude Code がセッションを開始する際、利用可能なすべての Skill とその説明のリストを構築します。Claude はこのリストをスキャンして「このリクエストに対応する Skill があるか？」を判断します。つまり、description フィールドは要約ではなく、いつこの Skill をトリガーすべきかを記述したものです。【注：このアドバイスはしばしば見落とされます。多くの人が description を書く際に「この Skill は何をするものか」を書いてしまいますが、Claude が必要としているのは「どのような状況でこの Skill を使うべきか」です。優れた description は機能説明というよりも、if-then（もし〜なら〜）の条件文のように読めるはずです。】

一部の Skills は、内部にデータを保存することで何らかの形の記憶を実現できます。最もシンプルな方法としては、追記専用のテキストログファイルや JSON ファイルを使用する方法があり、より複雑な方法としては SQLite データベース（SQLite）などを利用することも可能です。

例えば、standup-post Skill では standups.log を保持し、自分が行ったすべてのスタンドアップ報告を記録します。次回実行時には Claude が自身の履歴を読み取るため、昨日から現在までに何らかの変化があったかを把握できます。

Skills ディレクトリ内のデータは、Skill のアップデート時に削除される可能性があるため、データを保存する際は安定したフォルダを使用してください。現時点では ${CLAUDE_PLUGIN_DATA} を提供しています。

Claude に与えることができる最も強力なツールの一つがコードです。スクリプトやライブラリを Claude に提供し、その精力を組み合わせやオーケストレーション（編成）に集中させましょう。つまり、次に行うべきことを決定することに注力させる一方で、ボイラープレートコードの再構築は行わないようにします。

例えば、データサイエンス用の Skill には、イベントソースからデータを取得する関数群を配置できます。Claude により高度な分析を行わせるためには、以下のような補助関数群を提供することも可能です：

Claude はこれらの機能を組み合わせてスクリプトを即時生成し、より高度な分析を実行できます。例えば、「火曜日に何があったか？」といった質問に答えるようなタスクです。

Skills には、その Skill が呼び出された際にのみアクティブ化するフック（On Demand Hooks）を含めることができ、セッション全体を通じて有効に保つことが可能です。これは、主観的な判断を要するものや、常時実行したくないが、時々非常に有用なフックに適しています。

/careful — PreToolUse マッチャーを使用して、Bash 内の rm -rf、DROP TABLE、force-push、kubectl delete をインターセプトします。これは、自分が本番環境を操作していることを明確に知っている場合のみ必要です。常時有効にすると非常にストレスが溜まります【注：PreToolUse は Claude Code のフック（hook）メカニズムの一つで、Claude がツールを呼び出すたびにトリガーされます。このフック内で Claude が実行しようとしているコマンドを確認し、危険な操作に該当する場合は実行を阻止できます。ここで紹介されている /careful は、ユーザーが手動で呼び出した場合にのみ登録される、オンデマンド型の Skill です。】

/freeze — 特定のディレクトリ以外に対する Edit/Write 操作をすべてブロックします。デバッグ時に特に有用です。「ログを追加したいが、ついでに無関係なコードを誤って修正してしまう」といったケースに対応できます。

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

Skills を共有する方法は以下の 2 通りあります：

1. コードリポジトリに Skills をプッシュする（./.claude/skills 配下に配置）
2. プラグインとしてパッケージ化し、Claude Code プラグインマーケットプレイス（Plugin Marketplace）を構築して、ユーザーがプラグインのアップロードやインストールを行えるようにする（詳細はドキュメントを参照）

コードリポジトリ数が少ない小チームであれば、Skills をリポジトリにコミットするだけで十分です。ただし、各コミットされた Skill はモデルのコンテキストにわずかな負荷を追加します。規模が拡大すると、内部プラグイン市場を通じて Skills を配布し、メンバー自身がどのスキルをインストールするかを選択できるようになります。

どのような Skills をプラグイン市場に含めるべきか、またどのように提出すべきかについてはどうでしょうか？

これらを決定するための専任の中央チームはありません。むしろ、最も有用な Skills が自然に浮上することを好んでいます。試してほしい Skill がある場合は、GitHub のサンドボックスフォルダにアップロードし、Slack やその他のフォーラムで推奨してください。

ある Skill が十分な注目を集めた場合（その判断は Skill の作者が行います）、PR を提出してプラグイン市場へ移動させることができます。

注意すべき点として、質の低いまたは重複する Skills を作成するのは容易であるため、正式リリース前に何らかの審査メカニズムを設けることが重要です。

Skills 同士が相互に依存することを望む場合もあるかもしれません。例えば、ファイルをアップロードするための「ファイルアップロード Skill」と、CSV を生成してアップロードするための「CSV 生成 Skill」を持つようなケースです。この種の依存関係管理は現在、プラグイン市場や Skills 自体ではサポートされていませんが、他の Skills を名前で直接参照することは可能です。相手がインストール済みであれば、モデルが自動的に呼び出します。

Skill のパフォーマンスを把握するために、私たちは社内環境で Skill の使用状況を記録する「PreToolUse」フック（事前ツール使用フック）を使用しています（サンプルコードはこちら）。これにより、どの Skills が人気があるか、あるいは期待される頻度よりもトリガー回数が少ないかを特定できます。

Skills は AI エージェント（AI Agent）にとって極めて強力かつ柔軟なツールですが、これはまだ初期段階であり、私たちはその使い方を模索している最中です。

この記事を権威あるガイドとして捉えるのではなく、私たちの実践で検証された実用的なテクニックの集まりと捉えてください。Skills を理解する最良の方法は、実際に手を動かして始め、不断に実験し、何が自分に合うかを確認することです。私たちが持つ Skills の多くは、最初は数行のコードといくつかの失敗点から始まり、Claude が直面する新たな境界条件に対してメンバーが継続的に追加していくことで、徐々に改善されていきました。

この記事がお役に立てば幸いです。ご質問等ございましたら、お気軽にお知らせください。