Claude Codeを作りながら学んだこと: 私たちがSkillsを使う方法

• Claude Codeにおいて Skills は最もよく使われる拡張ポイントのひとつであり、Anthropic社内で数百のスキルを実運用して蓄積した実践的ノウハウが公開された
• スキルは単なるMarkdownファイルではなく、スクリプト、アセット、データなどを含むフォルダ構造であり、エージェントが探索して活用できる形になっている
• ライブラリリファレンス、製品検証、データ分析、コードスキャフォールディング、CI/CDなど 9つのスキルカテゴリ に分類され、優れたスキルはひとつのカテゴリにすっきり収まるべき
• スキル作成時は Gotchasセクション、ファイルシステム活用、段階的開示（Progressive Disclosure）、データ保存などの実践的なコツが重要
• 組織拡大時には 社内プラグインマーケットプレイス を通じてスキルを配布し、使用量測定フックで効果を追跡する構成が推奨される

---

Skillsとは何か

• Skillsについてのよくある誤解は「ただのMarkdownファイル」というものだが、実際には スクリプト、アセット、データなどを含むフォルダ 構造
• エージェントはこのフォルダを探索し、内容を発見し、操作できる
• Claude CodeではSkillsは さまざまな設定オプション を提供し、動的フック（dynamic hooks）の登録も可能
• 最も興味深いスキルは、こうした設定オプションとフォルダ構造を 創造的に活用 しているもの

スキルの9つのカテゴリ

• 内部で使われているスキルをすべて分類した結果、繰り返し現れる いくつかのカテゴリ にクラスター化された
• 良いスキルはひとつのカテゴリにきれいに収まり、分かりにくいスキルは複数カテゴリにまたがっている

• 1. Library & API Reference

  • ライブラリ、CLI、SDKを正しく使う方法を説明するスキル
  • 社内ライブラリだけでなく、Claude Codeがよく間違える 一般的なライブラリ も対象
  • リファレンスコードスニペットのフォルダや 注意点（gotchas）の一覧 を含むことが多い
  • 例: billing-lib（社内決済ライブラリのエッジケース）、internal-platform-cli（社内CLIラッパーの全サブコマンドと使用例）、frontend-design（デザインシステム適用の改善）

• 2. Product Verification

  • コードが正しく動作するかを テストして検証 する方法を記述するスキル
  • Playwright、tmuxなどの外部ツールと組み合わせて使うことが多い
  • Claudeの出力精度を保証するのに非常に有用で、エンジニアが 1週間投資してでも 検証スキルを優れたものにする価値がある
  • Claudeに出力を 動画で録画 させたり、各段階で状態に対する プログラム的アサーション を強制したりする手法が推奨される
  • 例: signup-flow-driver（登録→メール認証→オンボーディングをヘッドレスブラウザで実行）、checkout-verifier（Stripeのテストカードで決済UIを動かした後に請求書状態を検証）、tmux-cli-driver（TTYが必要な対話型CLIのテスト用）

• 3. Data Fetching & Analysis

  • データおよび監視スタックに接続するスキル
  • 認証情報を含むデータ取得ライブラリ、特定の ダッシュボードID、一般的なワークフロー案内などを含む
  • 例: funnel-query（登録→有効化→課金ファネルに必要なイベントとcanonical user_idを持つテーブル）、cohort-compare（2つのコホートの継続率・転換率比較と統計的有意性のフラグ付け）、grafana（データソースUID、クラスタ名、問題→ダッシュボードのルックアップテーブル）

• 4. Business Process & Team Automation

  • 繰り返し発生するワークフローを ひとつのコマンドで自動化 するスキル
  • 比較的シンプルな指示文だが、他のスキルやMCPへの複雑な依存関係を持つことがある
  • 以前の実行結果を ログファイルに保存 すると、モデルが一貫性を保ち、前回実行を反映しやすくなる
  • 例: standup-post（チケットトラッカー、GitHubアクティビティ、Slackを統合した定型スタンドアップ）、create-ticket（スキーマ強制と作成後ワークフロー）、weekly-recap（マージ済みPR＋クローズ済みチケット＋デプロイを要約投稿にまとめる）

• 5. Code Scaffolding & Templates

  • コードベース内の特定機能向けに フレームワークのボイラープレートを生成 するスキル
  • 組み合わせ可能なスクリプトと連携でき、コードだけではカバーしきれない 自然言語の要件 があるときに特に有用
  • 例: new-framework-workflow（アノテーション付きの新しいサービス／ワークフロー／ハンドラをスキャフォールディング）、new-migration（マイグレーションファイルのテンプレートと注意点）、create-app（認証、ロギング、デプロイ設定があらかじめ組み込まれた新しい社内アプリ）

• 6. Code Quality & Review

  • 組織内の コード品質を担保 し、コードレビューを支援するスキル
  • 最大限の堅牢性のために 決定論的なスクリプトやツール を含めることができる
  • フックやGitHub Actionの一部として自動実行することもできる
  • 例: adversarial-review（新しい視点のサブエージェントが批判→修正→反復を行い、指摘が重箱の隅レベルになるまで続ける）、code-style（Claudeが標準では苦手なコードスタイルを強制）、testing-practices（テストの書き方とテスト対象の案内）

• 7. CI/CD & Deployment

  • コードベース内でコードを 取得し、pushし、デプロイ するスキル
  • 他のスキルを参照してデータを収集することもある
  • 例: babysit-pr（PR監視→flakyなCIの再試行→マージコンフリクト解消→自動マージ有効化）、deploy-service（ビルド→スモークテスト→段階的トラフィックロールアウト→エラー率比較→退行時の自動ロールバック）、cherry-pick-prod（分離されたworktree→cherry-pick→コンフリクト解消→テンプレートPR作成）

• 8. Runbooks

  • 症状（Slackスレッド、アラート、エラーシグネチャなど）を入力として マルチツール調査を実行 し、構造化レポートを生成するスキル
  • 例: service-debugging（症状→ツール→クエリパターンのマッピング）、oncall-runner（アラート取得→一般的な原因チェック→結果整形）、log-correlator（リクエストIDで関連システム全体のログを収集）

• 9. Infrastructure Operations

  • 日常的な保守と運用手順を実行し、破壊的な作業に対するガードレール を含むスキル
  • エンジニアが重要な運用でベストプラクティスに従いやすくする
  • 例: resource-orphans（孤立したPod／ボリュームの探索→Slack通知→待機期間→ユーザー確認→段階的クリーンアップ）、dependency-management（組織の依存関係承認ワークフロー）、cost-investigation（ストレージ／egressコスト急増の原因調査向けバケットとクエリパターン）

スキル作成のヒント

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

  • Claude Codeはコードベースについてすでに多くを知っており、コーディングに関する基本的な見解も持っている
  • 知識中心のスキルを作るなら、Claudeの 一般的な思考から外れる情報 に集中すべき
  • frontend-designスキルは良い例で、Anthropicのエンジニアが顧客との反復を通じてClaudeの デザイン感覚を改善 するために作成したもので、Interフォントや紫のグラデーションのような典型的パターンを避けるよう構成されている

• Gotchasセクションを構築する

  • あらゆるスキルで 最もシグナル価値が高いコンテンツ がGotchasセクション
  • Claudeがスキル使用時によく遭遇する 失敗ポイント をもとに蓄積していくべき
  • 時間の経過とともにこうしたgotchasを継続的に更新するのが理想

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

  • スキルはフォルダなので、ファイルシステム全体をコンテキストエンジニアリングと段階的開示の手段 として活用すべき
  • Claudeにスキル内のどんなファイルがあるかを知らせれば、適切なタイミングで読み込む
  • 最もシンプルな形は、詳細な関数シグネチャや使用例を references/api.md のような別Markdownに分離すること
  • 最終出力がMarkdownの場合は assets/ フォルダにテンプレートファイル を含めることもできる
  • リファレンス、スクリプト、例などのフォルダがClaudeの作業効率を高める

• Claudeを過度に制約しない

  • Claudeは指示に従おうとするが、スキルは再利用性が高いため 過度に具体的な指示には注意 が必要
  • 必要な情報は与えつつ、状況に 柔軟に適応 できる余地を残すべき

• 設定（Setup）プロセスを設計する

  • 一部のスキルではユーザーから コンテキストを収集する設定段階 が必要
  • 例: スタンドアップをSlackに投稿するスキルなら、どのチャンネルに投稿するかを尋ねる必要がある
  • 良いパターン: 設定情報をスキルディレクトリの config.jsonファイルに保存 し、設定されていなければエージェントがユーザーに質問する
  • 構造化された複数選択質問を提示したい場合は AskUserQuestionツール の使用を指示できる

• Descriptionフィールドはモデルのためのもの

  • Claude Codeがセッションを開始すると、利用可能なすべてのスキルの description一覧を構築 する
  • Claudeはこの一覧を走査して「このリクエストに合うスキルはあるか？」を判断する
  • したがってdescriptionフィールドは要約ではなく、このスキルをいつトリガーすべきかの説明 である

• メモリとデータ保存

  • スキルには データを保存する形のメモリ を含められる
  • 単純なテキストログファイルやJSONファイルから SQLiteデータベース までさまざまな形が可能
  • 例: standup-postスキルがstandups.logにすべての作成履歴を保存していれば、次回実行時にClaudeが自身の履歴を読み、昨日以降の変更を把握できる
  • スキルディレクトリに保存したデータはスキル更新時に削除される可能性があるため、${CLAUDE_PLUGIN_DATA}という安定したフォルダ に保存すべき

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

  • Claudeに与えられる最も強力なツールのひとつが コードそのもの
  • スクリプトやライブラリを提供すれば、Claudeはボイラープレートの再構築ではなく 構成（composition）に集中 できる
  • 例: データサイエンス用スキルにイベントソースからデータを取得する ヘルパー関数ライブラリ を含める
  • Claudeはこれらの機能を組み合わせて その場でスクリプトを生成 し、「火曜日に何が起きたのか？」のような複雑な分析に活用できる

• On Demand Hooks

  • スキル呼び出し時にだけ有効化され、セッション中のみ持続 するフックを含められる
  • 常時実行するには重いが、特定状況で非常に有用な 強い方針を持つフック に向いている
  • 例:
    • /careful — rm -rf、DROP TABLE、force-push、kubectl delete を PreToolUseマッチャー でブロックし、本番作業時にのみ有効化
    • /freeze — 特定ディレクトリ以外のすべてのEdit/Writeをブロックし、デバッグ時の意図しない変更防止に有用

スキルの配布

• スキルの大きな利点のひとつは、チーム全体で共有 できる点
• 共有方法は2つある:
  • スキルを リポジトリにチェックイン する（./.claude/skills 配下）
  • プラグインとして作成しClaude Code Pluginマーケットプレイス にアップロードして、ユーザーがインストールする

• マーケットプレイス運営

  • 小規模チームが少数のリポジトリで作業する場合は、リポジトリにチェックインする方式が適している
  • チェックインされたスキルはモデルの コンテキストに少しずつ追加 されるため、規模が大きくなると社内プラグインマーケットプレイスが有利
  • マーケットプレイスに入れるスキルを決める 中央チームは存在せず、最も有用なスキルが自然に見つかる方式
  • 試してみたいスキルがあればGitHubの sandboxフォルダにアップロード し、Slackなどで案内する
  • 十分なトラクションが得られたら、スキルのオーナーが マーケットプレイスへ移すPR を出す
  • 質の低いスキルや重複スキルは簡単に作れてしまうため、リリース前の キュレーション機構 が重要

• スキルの合成（Composing Skills）

  • スキル間で 依存関係 が必要になる場合がある（例: ファイルアップロードスキル + CSV生成およびアップロードスキル）
  • マーケットプレイスやスキル自体に依存関係管理が ネイティブに組み込まれているわけではない が、他のスキルを名前で参照すれば、インストール済みの場合はモデルが呼び出す

• スキルの測定

  • スキルの成果を把握するため、PreToolUseフック で社内のスキル利用状況をロギングする
  • 人気のあるスキルや、期待よりトリガーされていないスキル を見つけるのに役立つ

結論

• Skillsはエージェント向けの非常に強力で柔軟なツールだが、まだ初期段階であり、誰もが最適な活用法を探っている途中 でもある
• この記事は確定的なガイドではなく、実践で効果があったヒント集 である
• ほとんどのスキルは数行とひとつのgotchaから始まり、Claudeが新たなエッジケースに出会うたびに人々が 継続的に追加して改善 してきた

[xguru]

最近Anthropicを見ていて感じるのは、開発担当者たちができるだけ自分たちの経験を共有しながら、自社製品をよりうまく使えるように導いているということです。

「AI時代の開発エコシステムはこうやって作っていくんです」と身をもって示している事例のように思えます。