ClaudeチームThariqが明かしたSkills設計9カテゴリ｜Anthropic社内で数百個動かす実践則

Claude Code開発チームのThariq氏が2026年3月17日にXで公開した長文記事は、わずか 数日でインプレッション685万を超える反響を呼びました。タイトルは「Lessons from Building Claude Code: How We Use Skills」。Anthropic社内で実際に数百のSkillsを 動かしてきた知見を、9つのカテゴリと9つの設計原則に整理した一次情報です。

国内ではClaude Skillsの存在自体は知られ始めましたが、「どう設計するか」「実運用 で何が壊れるか」といった生々しい話はほとんど翻訳されていません。本稿はThariq氏 の主張を逐条で日本語化し、社内で数百個動かすための実践則として再構成します。

結論を先に言うと、Skillsは「マークダウン1枚」ではなく「フォルダ」であり、Gotchasセクションとdescriptionの設計が成否の8割を決めます。

Claude Code全体の使い方は Claude Code完全ガイド2026：インストールから本番運用まで をご覧ください。

01 ThariqがXで公開した「数百スキル」運用の現実

Thariq氏はAnthropicでClaude Codeの開発に携わるエンジニアで、過去にもエージェント設計の全貌を語って国内外のエンジニアコミュニティで広く読まれてきました。今回の記事はその続編にあたります。

冒頭で氏が強調するのは、社内では「数百のSkillsが現役で動いている」という事実です。一見するとマーケティング上の誇張に聞こえますが、内訳を読み進めると確かに数百になることが分かります。コードベースに対するライブラリリファレンス、ビルドやデプロイ、データ取得、運用ランブック、社内業務の自動化など、エンジニアの一日のほぼ全ての操作にSkillsが対応しているからです。

ここで重要なのは、Skillsが「特殊な機能」ではなく「日常の延長」として位置づけられていることです。Anthropic社内のエンジニアは、新しい操作パターンを思いついたらまずSKILL.mdを書き、社内リポジトリやPlugin Marketplaceに置く。そして他のメンバーが同じ操作を行うときに自動的に呼び出される、という流れが定着しています。

Thariq氏は、Skillsを書くこと自体が一種の社内ナレッジ蓄積になっていると述べます。従来のWiki記事は読まれなければ価値がありませんが、SkillsはClaudeが業務の中で自動的に参照する。つまり「読まれることが保証されたドキュメント」になるわけです。

そしてもう一つ重要な指摘があります。Skillsはマークダウンファイル単体ではなく「フォルダ」だという点です。SKILL.mdの隣にスクリプト、テンプレート、データファイル、参照ドキュメントを置くことができ、Claudeはそれらを必要に応じて読み込みます。これがCursorルールやシステムプロンプトと根本的に異なる点です。

my-skill/
├── SKILL.md              # メインの定義とトリガー
├── references/
│   ├── api.md            # API仕様の詳細
│   └── gotchas.md        # 失敗パターン集
├── assets/
│   └── template.md       # 出力テンプレート
├── scripts/
│   └── helper.py         # 補助スクリプト
└── config.json           # 設定情報

このフォルダ構造があるからこそ、後述する「Progressive Disclosure(段階的開示)」が成立します。SKILL.md自体は短く保ち、詳細は必要なときだけ読み込む設計が可能になるのです。

02 9つのSkillsカテゴリで自分の業務を分類する

Thariq氏は社内で動いているSkillsを観察し、用途別に9つのカテゴリへ分類しました。 この分類は「何をSkillsにすべきか」を決める強力な思考フレームになります。自分の 業務を9カテゴリの軸で見直すと、未着手の自動化候補が浮かび上がります。

注目すべきは、この分類が「コード生成」よりも「運用と検証」に大きく寄っている点です。Claude Codeは「コードを書くツール」と見られがちですが、実際の社内活用では検証・配布・運用フェーズの方が件数として多いことが伺えます。

特に重要なカテゴリを3つ挙げると、まずLibrary & API Referenceです。社内ライブラリは公開ドキュメントが薄く、暗黙のルールが多い。これをSkillsに書いておくと、新規メンバーがClaude経由で正しい使い方を即座に習得できます。

次にRunbooks。オンコール対応中は焦りもあって判断ミスが起きがちですが、Skillsに手順を書いておけばClaudeが順序通りに案内してくれます。本番環境を直接触るリスクを下げる効果が大きい。

そしてCode Scaffolding & Templates。new-migrationのようなScaffoldingは「毎回似たコードを書くがミスると大事故」という典型例です。Skillsに型を埋め込んでおけば、Claudeが正しい雛形から始めてくれます。

Claude Skillsを徹底解説 ではSKILL.mdの基本構造を詳しく扱っています。本稿の9カテゴリ分類は、その基本を踏まえて「何を書くべきか」を決めるための上位レイヤーと考えてください。

03 Gotchasセクションが最大の差別化要因になる理由

Thariq氏が9つの設計原則の中で特に時間を割いて説明するのが、「Build a Gotchas Section(失敗パターンを蓄積するセクションを必ず作れ)」という指針です。

Gotchasとは、英語で「落とし穴」「ハマりやすい罠」を指す口語表現です。社内ライブラリを使う際の暗黙の前提、APIの非自明な挙動、特定環境でだけ起きるバグなど、ドキュメントに書かれない知識が当てはまります。

Skillsを書き始めた人がやりがちな失敗は、「使い方の手順」ばかり丁寧に書くことです。しかし手順だけならClaudeはコード補完や検索でもある程度書けます。本当に価値があるのは、「人間がハマって初めて知る非自明な落とし穴」を文字にすることです。

## Gotchas

- ChannelClient.send() はトークン期限切れ時にサイレントで成功扱いになる。
  必ず `verify=True` を渡して再検証を行うこと。
- v3.2 以降、retry_count=0 が無限リトライを意味するように変わった。
  明示的に retry_count=1 を渡さないと本番が詰まる。
- 内部APIの `/v2/users` はページサイズが100固定。それより大きい limit
  を渡すと 200 が返るが、レスポンスは100件しかない。

このようにGotchasを書き溜めておくと、Claudeが該当ライブラリを使うコードを書く度に同じ罠を回避するようになります。Gotchasセクションが厚いSkillsほど、生成コードのバグ密度が下がるというのがThariq氏の観察です。

Gotchasを増やすには「失敗のたびに追記する」運用が有効です。本番障害やレビュー指摘で見つかった非自明な前提は、その日のうちにSkillsへフィードバックする。これを徹底すると、Skillsが社内のポストモーテム蓄積場としても機能します。

逆にThariq氏が戒めるのは、「Don’t State the Obvious(自明なことを書くな)」という原則です。「pythonでは型ヒントを書こう」「テストを書きましょう」のような一般論はClaudeが既に知っており、書くだけプロンプトを汚染します。

Gotchasの判断基準はシンプルで、「自分が初見でこの情報を持っていなかったら本番を壊した可能性があるか?」を自問することです。Yesなら書く、Noなら書かない。これだけでSkillsの密度が大幅に上がります。

04 Progressive Disclosureで肥大化を防ぐ

Skillsを書き続けると必ずぶつかる壁が、SKILL.md自体の肥大化です。1ファイルが2000行を超えるとClaudeのコンテキストを圧迫し、他のスキルや会話履歴を押し出してしまいます。

Thariq氏が処方箋として示すのは「Use the File System & Progressive Disclosure(ファイルシステムと段階的開示を活用せよ)」という原則です。つまり、SKILL.mdは目次と最重要情報だけに絞り、詳細はサブファイルへ追い出します。Claudeは必要に応じてサブファイルを読みに行く設計にする。

---
name: internal-api-helper
description: 社内APIを叩くコードを書く時に呼び出す。ChannelClient v3
  以降のretryやページングの罠を回避し、認証ヘッダーを正しく付与する。
---

社内APIヘルパー。詳細は以下のリファレンスを参照。

- 全エンドポイント一覧: references/api.md
- 落とし穴と過去障害: references/gotchas.md
- レスポンステンプレート: assets/response_template.json

## 最も重要な3点

1. 必ず `Authorization: Bearer ${INTERNAL_API_TOKEN}` を付ける
2. v3 以降 retry_count=0 は無限リトライ。明示的に 1 を指定する
3. ページング上限は100件固定。それ以上は分割呼び出し

このようにSKILL.mdは100〜200行に抑え、詳細はreferences/配下へ分離します。Claudeは初回呼び出し時にSKILL.mdだけを読み、必要に応じてreferences/api.mdをRead Toolで開く。この段階的開示によってコンテキスト消費を最小化できます。

Progressive Disclosureは、Skillsの数が増えてからこそ効きます。10個のSkillsが各2000行ずつ常駐すると2万行ですが、各200行に圧縮できれば2000行で済む。Skillsの数を増やしながらコンテキスト消費を抑えるための必須テクニックです。

合わせてThariq氏は「Avoid Railroading Claude(Claudeを線路に乗せて縛りつけるな)」とも述べます。手順を細かく規定しすぎると、Claudeが状況に応じた判断をできなくなる。意図と制約だけ書き、具体的な手順はClaudeに委ねるバランスが必要です。

Claude Codeのベストプラクティス完全ガイド2026年版でも触れていますが、エージェントに対する指示は「禁止事項と意図」を書き、「ステップbyステップの手順」は最小限にとどめるのが鉄則です。

05 descriptionは要約じゃなく「呼び出しトリガー」だ

Thariq氏が原則の中で最も誤解されやすいと指摘するのが、「The Description Field Is For the Model(descriptionはモデルのための欄)」という点です。

SKILL.mdのfrontmatterに書くdescriptionは、人間が読むメタ情報ではありません。Claudeが「いつこのスキルを呼び出すべきか」を判断する唯一の材料です。だからこそ、要約ではなく「トリガー条件」として書く必要があります。

悪い例と良い例を比較してみましょう。

# 悪い例: 要約として書いている
description: "社内APIを叩くためのヘルパースキル"

# 良い例: トリガー条件として書いている
description: "社内ChannelClient APIを呼ぶコードを書くとき、または
  Authorization Bearer や retry_count を含むコードに触れるときに呼ぶ。
  v3以降の非自明な挙動とページング上限を回避する。"

良い例の特徴は3つあります。第一に「いつ呼ぶか」が明示されている。第二に「何を回避できるか」が分かる。第三に具体的なキーワード(ChannelClient、Authorization、retry_count)が含まれている。

Claudeは多数のSkillsの中から最適なものを選ぶとき、descriptionの記述だけを見て判断します。ここに「ヘルパースキルです」しか書いていないと、似たようなスキルが複数あったときに正しく選ばれません。

「いつ」「何のために」「どんなキーワードがあれば」を1〜3文で書くのがコツです。長すぎると判断のノイズになり、短すぎると呼び出されません。

---
name: oncall-runbook
description: "本番環境のサービス障害対応中、特にレイテンシ悪化や5xx
  急増を見たときに呼ぶ。Datadog/Grafanaクエリと過去の同種障害の修
  正手順を提示する。Slackの#oncallチャンネルへの状況報告テンプレ
  も含む。"
---

このようにdescriptionは「Claudeがあなたの代わりに判断するための材料」として書く。要約として書きたくなる衝動を抑えるのが、Skills設計の最初の関門です。

加えてThariq氏は「Think through the Setup(セットアップを真剣に考えろ)」とも述べます。スキル実行に必要なAPIキーやエンドポイントはconfig.jsonに保存し、Claudeが起動時に読み込めるようにする。環境変数だけに依存すると環境差異でハマりやすいからです。

06 On Demand Hooksでrm -rf事故を防ぐ

Thariq氏が「これがないと社内Claude運用は怖くて使えない」と言うのが、「On Demand Hooks(必要に応じて起動するフック)」の仕組みです。

Hooksとは、Claude Codeが特定のイベント(ツール呼び出し前、ファイル編集前など)で実行するスクリプトです。Skills自体とは別レイヤーですが、Skillsと組み合わせて初めて社内運用に耐えうる安全性が出ます。

代表例として氏が紹介するのが/carefulと/freezeです。

# /careful スキル: rm -rf や DROP TABLE を絶対実行させない
# .claude/hooks/pre-tool-use.sh

#!/bin/bash
TOOL_INPUT="$1"

# 危険なコマンドパターンを正規表現で検出
if echo "$TOOL_INPUT" | grep -E "rm -rf|DROP TABLE|DELETE FROM.*WHERE 1=1"; then
  echo "ERROR: 危険なコマンドが検出されました。/careful モードでは実行できません。"
  exit 1
fi

exit 0

/carefulを有効にしている間、Claudeがrm -rf /やDROP TABLE usersを実行しようとしてもPreToolUseフックが弾きます。Claudeのプロンプト指示に頼らず、シェルレベルで拒否する点が重要です。

/freezeはもう少し細かく、「特定ディレクトリ以外の編集を禁止する」仕組みです。たとえばリファクタリング中に「lib/配下だけ触ってほしい」場合、freezeを有効にすれば他のディレクトリへの編集が物理的にブロックされます。

# /freeze スキル: 指定ディレクトリ外の編集を禁止
ALLOWED_DIR="lib/"
EDIT_TARGET="$2"

if [[ "$EDIT_TARGET" != "$ALLOWED_DIR"* ]]; then
  echo "ERROR: $ALLOWED_DIR 以外の編集は freeze モードで禁止です。"
  exit 1
fi

これらの仕組みは、「人間が忘れていてもシステムが守ってくれる」安全網になります。Claudeに毎回「rm -rfは禁止」と書くのではなく、フックで物理的に防ぐ方が確実です。

Thariq氏はもう一つ「Memory & Storing Data(メモリとデータ保存)」という原則も挙げます。Skillsの実行履歴や状態は、${CLAUDE_PLUGIN_DATA}配下にファイルとして保存できる。例えばstandups.logに毎日の進捗を追記していけば、weekly-recapスキルがそれを集計して週報を生成する、といった連携が可能です。

# standup-post スキル内で
echo "$(date +%Y-%m-%d): $STANDUP_CONTENT" >> "${CLAUDE_PLUGIN_DATA}/standups.log"

# weekly-recap スキル内で
tail -7 "${CLAUDE_PLUGIN_DATA}/standups.log" | claude_summarize

このように追記ログを使うと、Skillsが「ステートレスな関数」から「状態を持つエージェント」へと進化します。データの保存場所が標準化されているため、複数のSkillsで同じログを共有できる点も便利です。

07 Plugin Marketplaceでスケールさせる配布戦略

最後にThariq氏が触れるのが、Skillsの配布戦略です。社内に数百のSkillsがあるとき、それをどう共有・更新するかは設計と同じくらい重要です。

氏が示す配布方式は2つあります。一つ目はリポジトリ同梱方式で、.claude/skills/配下にSkillsを置いてgit管理する。小規模チームではこれで十分です。CIに参加するメンバー全員が同じSkillsを使えるため、レビューや更新もPRで完結します。

my-repo/
├── .claude/
│   ├── skills/
│   │   ├── deploy-staging/
│   │   │   ├── SKILL.md
│   │   │   └── scripts/
│   │   ├── new-migration/
│   │   └── adversarial-review/
│   └── settings.json
├── src/
└── README.md

二つ目はPlugin Marketplace方式で、Anthropic公式のプラグイン仕組みに乗せて社内マーケットプレイスを構築する。Anthropic社内ではこちらが主流のようで、Skillsをプラグインとしてバージョン管理し、メンバーが必要なものだけインストールする運用です。

Marketplace方式の真価はバージョン管理にあります。Skillsもコードと同じく壊れるため、安定版とベータ版を分けて配布できる仕組みは大規模運用で必須になります。

合わせて重要なのが「Store Scripts & Generate Code(スクリプトを保存し、コードを組み立てさせる)」原則です。Skillsの中には、Claudeがそのまま実行できるシェルスクリプトやPythonヘルパー関数を含めておく。Claudeはそれらを部品として組み合わせ、必要に応じてカスタマイズする使い方ができます。

# scripts/db_query.py
def safe_query(sql: str, params: dict) -> list[dict]:
    """SQLインジェクション対策込みのクエリ実行"""
    if not is_read_only(sql):
        raise ValueError("Read-only クエリのみ許可")
    return execute(sql, params)

この関数をSkills内に置いておけば、Claudeは「DBから読むコードが必要」と判断したときにsafe_queryを呼ぶコードを組み立てます。Claudeに毎回安全策を書かせるのではなく、安全な部品を渡しておく方が確実で速い。

最後に運用面の話として、Thariq氏はPreToolUseフックでスキル使用ログを取ることを勧めます。どのスキルが何回呼ばれているかを集計し、使われていないSkillsを定期的に削除する。Skillsは増やすだけでなく減らす運用も重要、というのが社内の知見です。

// .claude/hooks/pre-tool-use.json
{
  "command": "echo \"$(date +%s),${SKILL_NAME}\" >> ~/.claude/skill-usage.log"
}

このログを月次で集計し、3カ月使われていないSkillsはアーカイブするルールにすると、Skillsの総数が常に「現役で価値あるもの」だけに絞られます。

国内でClaude Codeをチーム導入する際は、まずClaude Code開発者Thariqが語るエージェント設計の全貌で全体像を掴み、その上で本稿の9カテゴリと9原則をチェックリストとして使うのがおすすめです。

参照ソース

• Thariq氏のX投稿(685万imp)
• Lessons from building Claude Code: How We Use Skills(公式blog記事に該当)
• Anthropic Claude Code 公式ドキュメント