Claude Code開発者が明かすSkills活用の実践知 — Anthropic内部で数百個を運用して見えた9つのカテゴリと設計原則

この記事で得られること

• Claude Code の Skills がどんな種類に分かれるか（9カテゴリの分類体系）
• Anthropic 内部で数百個を運用して見えた効果的な Skill の書き方
• Skills をチームに展開する際のベストプラクティス
• 開発者が今日から始められる具体的なアクション

---

一次ソース

2026年3月18日、Anthropic の Claude Code チームのエンジニア Thariq Shihipar が X（旧Twitter）で「Lessons from Building Claude Code: How We Use Skills」と題した長文記事を公開した。

投稿は 3.1M views、10K いいね、1.6K リポスト を記録し、Hacker News でもフロントページ入りするなど、AI 開発者コミュニティで大きな反響を呼んでいる。

Thariq は MIT Media Lab 出身で、YC W20 バッチのゲーム会社を創業（$17MM調達）、SaaS スタートアップの売却を経て Anthropic に参画。現在は Claude Code チームでスキルシステムの設計に直接関わるエンジニアだ。つまりこの記事は、Skills の設計者自身による実践レポートという位置づけになる。

---

Skills とは何か — 「ただの Markdown」ではない

Skills は Claude Code の最も人気の高い拡張ポイントだ。柔軟で、作りやすく、配布しやすい。

しかし Thariq が最初に指摘するのは、よくある誤解についてだ。

Skills は「ただの Markdown ファイル」ではない。最も面白い Skills は、スクリプト、参照ファイル、データを含むフォルダ構造を創造的に活用している。

Skills は単なるプロンプトの固定ではなく、フォルダ全体がエージェントの作業環境になる。references/ に API ドキュメントを置き、scripts/ に検証スクリプトを配置し、assets/ にテンプレートを格納する。Claude Code はこれらを必要に応じて読み込み、組み合わせて使う。

---

Anthropic が見出した 9 つの Skills カテゴリ

社内の全 Skills を整理した結果、繰り返し現れるパターンが見えてきたという。Thariq は「最良の Skills は 1 つのカテゴリに明確に属し、最も混乱する Skills は複数カテゴリにまたがっている」と指摘する。

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

特定のライブラリや CLI の正しい使い方を教える Skills。内部ライブラリや、Claude が間違えやすい外部ライブラリに効果的。

例	内容
billing-lib	社内課金ライブラリのエッジケースと落とし穴
internal-platform-cli	内部 CLI の全サブコマンドと使用例
frontend-design	デザインシステムを Claude に理解させる

2. プロダクト検証

コードが正しく動作するかをテスト・検証する Skills。Playwright、tmux などの外部ツールと連携する。

Thariq の強い推奨：「検証系 Skills にエンジニア 1 人が 1 週間を費やす価値がある」

具体的なテクニックとして、Claude にテスト過程の動画を録画させる（何をテストしたか確認できる）、各ステップでプログラム的な状態チェックを強制する Hook の活用が挙げられている。

例	内容
signup-flow-driver	ヘッドレスブラウザで登録→メール認証→オンボーディングを通しで実行
checkout-verifier	Stripe テストカードで決済 UI を駆動し、請求状態を検証
tmux-cli-driver	TTY が必要なインタラクティブ CLI のテスト

3. データ取得・分析

社内のデータソースやモニタリングシステムに接続する Skills。認証情報、ダッシュボード ID、標準的なクエリパターンを含む。

例	内容
funnel-query	登録→活性化→課金の JOIN 方法とテーブル定義
cohort-compare	2 群のリテンション・CVR 比較、統計的有意差の検出
grafana	データソース UID、クラスタ名、問題→ダッシュボード対照表

4. 業務プロセス自動化

反復的なワークフローを 1 コマンドに圧縮する Skills。過去の実行ログを保持することで、モデルの一貫性維持に役立つ。

例	内容
standup-post	チケット＋GitHub 活動＋Slack → スタンドアップ報告
create-ticket	必須フィールドの強制＋作成後の通知ワークフロー
weekly-recap	マージ済み PR＋クローズ済みチケット＋デプロイ → 週報

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

プロジェクト固有のボイラープレートを生成する Skills。自然言語の要件が絡み、純粋なコード生成では対応しきれない場面で威力を発揮する。

例	内容
new-workflow	アノテーション付きの新サービス/ワークフローを作成
new-migration	マイグレーションテンプレート＋よくある落とし穴
create-app	認証・ロギング・デプロイ設定が事前接続された新アプリ

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

組織内のコード品質を維持し、コードレビューを支援する Skills。GitHub Action や Hook での自動実行との相性が良い。

例	内容
adversarial-review	別視点のサブエージェントが粗探し→修正→反復
code-style	Claude がデフォルトで守れないスタイルの強制
testing-practices	テストの書き方と対象の方針

7. CI/CD・デプロイ

コードのフェッチ、プッシュ、デプロイを支援する Skills。他の Skills やデータを参照して判断する複合型が多い。

例	内容
babysit-pr	PR 監視→flaky CI リトライ→コンフリクト解消→自動マージ
deploy-service	ビルド→スモークテスト→段階的トラフィック切替→異常時ロールバック
cherry-pick-prod	隔離ワークツリーでの cherry-pick→コンフリクト解決→PR 作成

8. 運用手順書（Runbook）

症状（Slack スレッド、アラート、エラーシグネチャ）を受け取り、マルチツール調査を経て構造化レポートを出力する Skills。

例	内容
service-debugging	症状→ツール→クエリパターンの対応付け
oncall-runner	アラート取得→共通原因チェック→発見事項のフォーマット
log-correlator	リクエスト ID から関連システムのログを横断収集

9. インフラ運用

定常メンテナンスや運用手順を実行する Skills。破壊的操作にはセーフガードが不可欠。

例	内容
resource-orphans	孤立 Pod/Volume 検出→Slack 通知→確認→クリーンアップ
dependency-management	依存パッケージの承認ワークフロー
cost-investigation	ストレージ/転送量の請求急増の原因調査

---

Skill 設計の 7 つの原則

カテゴリを理解した上で、実際にどう書くか。Thariq が共有した設計原則をまとめる。

1. 「当たり前のこと」を書かない

Claude はコードベースについて多くを知っており、プログラミング一般についても豊富な知識を持つ。知識系 Skills を書く場合は、Claude を通常の思考パターンから引き出す情報に焦点を当てるべきだ。

frontend-design Skill が好例として挙げられている。Anthropic のエンジニアが顧客との反復を通じて作成したもので、Inter フォントや紫グラデーションといった「AI っぽいデザインパターン」を回避させる。

2. 「よくある落とし穴」セクションを育てる

どの Skill でも最もシグナルの強い部分は「Gotchas（よくある落とし穴）」セクションだ。

Claude が実際にその Skill を使う中で遭遇した失敗パターンを蓄積していく。理想的には、使うたびに更新される生きたドキュメントになる。

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

Skill はフォルダであり、ファイルシステム全体がコンテキストエンジニアリングと段階的開示の手段になる。

• references/api.md に詳細な関数シグネチャを分離
• assets/ にテンプレートファイルを配置
• scripts/ に検証スクリプトを格納

「ここにこのファイルがある」と SKILL.md に書いておけば、Claude は必要な時に読みに行く。

4. Claude を過度に制約しない

Claude は指示に忠実に従おうとする。Skills は再利用性が高いので、指示が具体的すぎないように注意すべきだ。

必要な情報は与えつつ、状況に応じた柔軟性も残す。

5. セットアップフローを考える

Skill によってはユーザーごとの設定が必要になる。Skill ディレクトリ内の config.json に設定を保存し、未設定なら Claude がユーザーに尋ねるパターンが推奨されている。構造化された選択肢を提示したい場合は AskUserQuestion ツールの活用も。

6. description はモデルのためのもの

Claude Code は起動時に全 Skills の description 一覧を作成し、リクエストに対応する Skill があるか判断する。つまり description は要約ではなく、トリガー条件の記述だ。

7. 記憶とデータ永続化を組み込む

Skill 内にデータを保存することで「記憶」を実現できる。テキストログや JSON から SQLite まで柔軟に選べる。

例えば standup-post が standups.log を保持すれば、次回実行時に「昨日からの差分」を自動で判断できる。永続データは ${CLAUDE_PLUGIN_DATA} に保存するのが推奨。

---

チーム展開の戦略

リポジトリ直接 vs Plugin Marketplace

方式	適用場面	注意点
.claude/skills/ にコミット	少数リポジトリの小規模チーム	コミットごとにモデルのコンテキストが増加
Plugin Marketplace	大規模組織	メンバーが必要な Skills を選択インストール

品質管理のプロセス

Anthropic では集中管理チームを置かず、有機的に有用な Skills を見つけている。

1. 新しい Skill を GitHub のサンドボックスフォルダにアップロード
2. Slack などで共有して試用を促す
3. 支持を集めたら Marketplace への PR を提出

「品質の低い、または冗長な Skills は簡単に作れてしまう。公開前の何らかのレビュープロセスが重要」

Skills の効果測定

PreToolUse Hook でスキルの使用状況をログに記録する仕組みを構築。これにより、人気の Skills や、トリガー率が期待より低い Skills を特定できる。実装例の Gist も公開されている。

On-demand Hooks — 必要な時だけ制約を有効化

Skills には起動時だけ有効になる Hook を含められる。常時有効にすると煩わしいが、特定の状況では極めて有用な制約を実現する。

コマンド	内容
/careful	rm -rf、DROP TABLE、force-push、kubectl delete をブロック。本番環境操作時のみ有効化
/freeze	特定ディレクトリ外の Edit/Write をブロック。デバッグ中に無関係なファイルを触らせない

---

開発者への実践的なアクション

Thariq の知見を踏まえ、今日から始められるステップを整理する。

Step 1: 自分の「落とし穴」を 1 つ Skills 化する

最も ROI が高いのは、自分が繰り返し遭遇するエラーや非効率を Skills にすること。プロジェクト固有のビルド手順、デプロイフロー、テスト方法など。最初は 10 行の Markdown で十分だ。

Step 2: 検証系 Skills に投資する

Thariq が「エンジニア 1 人が 1 週間費やす価値がある」と断言したカテゴリ。E2E テスト、スモークテスト、状態検証を Skill 化することで、Claude の出力品質が安定する。

Step 3: フォルダ構造を活用する

SKILL.md 1 ファイルで完結させず、references/、scripts/、assets/ を使って段階的に情報を開示する設計にする。

Step 4: description を「トリガー条件」として書く

「このスキルは〇〇をする」ではなく、「〇〇という状況で使う」という書き方に。Claude が正しく Skills を選択できるかどうかは description の質で決まる。

---

まとめ

Thariq は記事の結びでこう述べている。

Skills はエージェント AI にとって極めて強力で柔軟なツールだが、まだ初期段階にあり、私たちは皆、うまく使う方法を模索している最中だ。

私たちの Skills のほとんどは、数行のテキストと 1 つの落とし穴メモから始まった。Claude が新しいエッジケースに遭遇するたびに人々が追記していくことで、徐々に良くなっていったのだ。

Skills は「書いて終わり」ではなく、チームで育てる生きたドキュメントだ。最初の一歩は小さくていい。使いながら落とし穴を追記し、スクリプトを追加し、フォルダ構造を充実させていく。その反復こそが、AI エージェント時代の「開発力」の差を生む。

---