Anthropic で Claude Code を開発している Thariq が、社内での大規模なスキル活用から得た知見をまとめたノートが公開された。スキルは Claude Code の最も使われる拡張ポイントの一つであり、柔軟で作りやすく配布もしやすい。しかしその柔軟性ゆえに「何が正解か」を判断しにくいという問題もある。本記事はそのノートの内容を日本語でまとめたものだ。
スキルとは何か
スキルは「ただの Markdown ファイル」という誤解が多いが、実際にはスクリプト・アセット・データなどを含むフォルダー全体がスキルだ。Claude Code では動的なフックの登録など多彩な設定オプションも提供されている。
最も面白いスキルは、こうした設定オプションやフォルダー構造をクリエイティブに活用しているものだ。
スキルの 9 つのカテゴリ
社内のスキルを棚卸ししたところ、いくつかのカテゴリに分類できた。最も優れたスキルは一つのカテゴリに綺麗に収まる。自組織でどのカテゴリが欠けているかを確認するのに役立つ。
1. ライブラリ・API リファレンス
ライブラリ、CLI、SDK の正しい使い方を説明するスキル。内部ライブラリや Claude Code が苦手とする一般的なライブラリを対象にする。参照コードスニペットのフォルダーや、Claude が避けるべき「落とし穴（gotchas）」リストを含めることが多い。
例:
billing-lib— 社内課金ライブラリのエッジケースや注意点internal-platform-cli— 社内 CLI の全サブコマンドと使用例frontend-design— 自社デザインシステムに Claude を合わせる
2. プロダクト検証
コードが正しく動作しているかをテスト・検証するスキル。Playwright や tmux などの外部ツールと組み合わせることが多い。検証スキルは Claude のアウトプットの正確性を担保するために極めて有用で、エンジニアが 1 週間かけて磨き上げる価値がある。
出力の動画録画や各ステップでのプログラムによるアサーションなどの手法も有効だ。
例:
signup-flow-driver— サインアップ → メール確認 → オンボーディングをヘッドレスブラウザで実行checkout-verifier— Stripe テストカードでチェックアウト UI を操作し、請求書の状態を確認tmux-cli-driver— TTY が必要なインタラクティブ CLI テスト用
3. データ取得・分析
データ・監視スタックに接続するスキル。認証情報付きでデータを取得するライブラリ、特定のダッシュボード ID、一般的なワークフローの手順などを含む。
例:
funnel-query— サインアップ → アクティベーション → 有料への変換を追うためのイベント結合方法cohort-compare— 2 コホートのリテンション・コンバージョン比較と有意差フラグgrafana— データソース UID、クラスター名、問題 → ダッシュボード対応表
4. ビジネスプロセス・チーム自動化
反復的なワークフローをコマンド一つに自動化するスキル。比較的シンプルな指示だが、他のスキルや MCP への複雑な依存関係を持つことがある。ログファイルに前回の実行結果を保存することで、モデルの一貫性を保ちやすくなる。
例:
standup-post— チケットトラッカー・GitHub アクティビティ・過去 Slack を集約してスタンドアップ投稿create-<ticket-system>-ticket— スキーマ（有効な enum 値・必須フィールド）を強制し、作成後のワークフローも自動化weekly-recap— マージ PR・クローズチケット・デプロイ → 週次レポート
5. コードスキャフォールディング・テンプレート
コードベースの特定機能向けフレームワークボイラープレートを生成するスキル。スクリプトと組み合わせて使うことも多い。スキャフォールディングに自然言語による要件がある場合に特に有効だ。
例:
new-<framework>-workflow— アノテーション付きの新しいサービス/ワークフロー/ハンドラーをスキャフォールドnew-migration— マイグレーションファイルテンプレートと一般的な落とし穴create-app— 認証・ロギング・デプロイ設定が事前に組み込まれた新規内部アプリ
6. コード品質・レビュー
コード品質を強制し、コードレビューを支援するスキル。最大の堅牢性を得るために決定論的なスクリプトやツールを含めることができる。フックや GitHub Actions の一部として自動実行するのも有効だ。
例:
adversarial-review— フレッシュな視点のサブエージェントを起動して批評し、指摘が些細なものになるまで反復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 の通常の思考パターンを外すような情報に集中する。
frontend-design スキルはその好例だ。Anthropic のエンジニアが顧客との反復を通じて Claude のデザインセンスを改善したもので、Inter フォントや紫のグラデーションといった典型的なパターンを避けるよう学習させている。
Gotchas セクションを作る
スキルの中で最も情報密度が高いのが Gotchas（落とし穴）セクションだ。Claude がスキルを使う際に実際につまずいた失敗パターンから構築する。スキルは使われるにつれて更新し、gotchas を積み重ねていくのが理想だ。
ファイルシステムとプログレッシブディスクロージャーを活用する
スキルはフォルダーであることを活かし、ファイルシステム全体をコンテキストエンジニアリングの手段として使う。スキル内のファイルを Claude に伝えることで、Claude は適切なタイミングでそれを読み込む。
最もシンプルな形は、詳細な関数シグネチャや使用例を references/api.md などに分割して参照させること。出力がマークダウンファイルなら assets/ にテンプレートを置いておくのも有効だ。
Claude を縛りすぎない
スキルは再利用されるため、指示が具体的すぎると逆効果になる。Claude に必要な情報を渡しつつ、状況への適応力を残すこと。
セットアップを考慮する
スキルによってはユーザーからのコンテキストが必要な場合がある。たとえばスタンドアップを Slack に投稿するスキルなら、どのチャンネルに投稿するかを尋ねるべきだ。
推奨パターンは、スキルディレクトリ内の config.json にセットアップ情報を保存すること。設定が未完了なら Claude がユーザーに尋ねる。複数選択の構造化質問には AskUserQuestion ツールを使うよう指示できる。
description フィールドはモデル向けに書く
Claude Code はセッション開始時に全スキルの description を一覧化し、「このリクエストに合うスキルはあるか？」を判断する。つまり description はサマリーではなく、いつこのスキルをトリガーするかの説明だ。
メモリとデータの保存
スキル内にデータを保存してメモリの一形態として活用できる。追記専用テキストログや JSON ファイル、SQLite データベースなど、用途に応じて選択する。
たとえば standup-post スキルが standups.log に全投稿を記録していれば、次回実行時に Claude は履歴を参照して昨日からの変更点を把握できる。
注意: スキルディレクトリ内のデータはスキルアップグレード時に削除される可能性がある。安定した保存場所として ${CLAUDE_PLUGIN_DATA} が提供されている（プラグインごとに固定フォルダーが割り当てられる）。
スクリプトを置いてコードを生成させる
Claude に最も力を発揮させるのはコードだ。スクリプトとライブラリを与えることで、Claude は「次に何をすべきか」の判断に集中でき、ボイラープレートの再構築に時間を使わなくてよくなる。
データサイエンス用スキルにはイベントソースからデータを取得するライブラリを置き、Claude がそれをその場で組み合わせてスクリプトを生成する、という使い方が強力だ。
オンデマンドフック
スキルには「呼び出されたときだけ有効化され、セッション中持続する」フックを含めることができる。常時有効にするほどではないが、特定場面では非常に便利なフックに適している。
例:
/careful—rm -rf、DROP TABLE、force-push、kubectl deleteをブロック。本番に触れる時だけ有効化したいルール/freeze— 特定ディレクトリ以外の Edit/Write をブロック。デバッグ中に「ログを追加しようとして無関係なコードを直してしまう」問題の防止
スキルの配布
スキルの最大の利点の一つはチームへの共有だ。配布方法は主に 2 つある。
- リポジトリにチェックイン（
./.claude/skills/配下） - プラグインマーケットプレイスで配布（Claude Code Plugin のドキュメント参照）
小規模チームでリポジトリ数が少ない場合はリポジトリへのチェックインが有効。ただしチェックインされたスキルはモデルのコンテキストに影響するため、スケールするにつれて内部プラグインマーケットプレイスでチームに選択権を与える方が良い。
マーケットプレイスの管理方法
Anthropic では中央集権的な決定チームを設けず、有機的に役立つスキルを発見する方針をとっている。スキルを試してほしい場合は GitHub のサンドボックスフォルダーにアップロードして Slack などで周知する。十分なトラクションが得られたら、マーケットプレイスへの移動 PR を出す。
悪いスキルや重複スキルを作りやすいため、リリース前の何らかのキュレーション方法を持つことが重要だ。
スキルの組み合わせ
スキル間の依存関係も設定できる。ファイルアップロードスキルと CSV 生成スキルを組み合わせるような場合、依存関係管理はネイティブには組み込まれていないが、他のスキル名を参照するだけでモデルがインストール済みスキルを呼び出してくれる。
スキルの計測
スキルの利用状況を把握するために、PreToolUse フックを使ってスキル使用をログに記録できる（サンプルコード）。これにより人気のスキルや、期待より少ない頻度でしかトリガーされないスキルを特定できる。
まとめ
スキルは非常に強力で柔軟なエージェント向けツールだが、まだ黎明期であり、最適な使い方は模索中だ。
このまとめは決定版のガイドというよりも、実際に機能することが確認された有用なヒントの詰め合わせだ。スキルを理解する最善の方法は、実際に始めて実験し、何が自分に合うかを確認すること。多くのスキルは数行と一つの gotchas から始まり、Claude が新しいエッジケースに当たるたびに人々が追加することで良くなっていった。