Anthropic 流の Claude Code skill の書き方：9 種類の skill と 9 つの実践的な教訓

2026年10月3日

Claude Code の skill（スキル）は、指示、スクリプト、資料をまとめたフォルダで、AI が合う仕事に出会ったとき自分で見つけて使います。Anthropic の Claude Code チームは毎日 skill を使っていて、Thariq Shihipar（Anthropic）が claude.dev の「Lessons from building Claude Code: How we use skills」でそのやり方を紹介しました。この記事では、彼らがよく書く 9 種類の skill と、skill を本当に役立つものにする 9 つの教訓をまとめます。読む時間は約 15 分です。

skill が何かまだわからない方は、先に Claude Skills とはと Claude Code とは（どちらもベトナム語）をどうぞ。

準備

Claude Code をインストール済み（インストールは無料、使うには Claude の有料プランか API アカウントが必要）。
繰り返している仕事：週報の投稿、サイト修正後のチェック、売上データの集計など。
プロジェクト内の .claude/skills/ フォルダ。skill ごとにサブフォルダを作り、SKILL.md を置きます。

元記事によると、いちばん多い誤解は「skill はただの markdown ファイル」という思い込みです。実際はフォルダ全体で、AI が読んで使えるスクリプト、テンプレート、データを入れられます。

手順

ステップ 1：skill の種類を正しく選ぶ

Anthropic は自社の skill を 9 種類に分けています。良い skill は1 つの種類にきれいに収まります。複数にまたがる skill は AI を混乱させます。

ライブラリと API のリファレンス：ライブラリやコマンドラインツールの正しい使い方と、よくある落とし穴。
プロダクトの検証：製品が正しく動くかのテスト方法。元記事によると、Anthropic 社内でClaude の出力品質をいちばん目に見えて上げたのがこの種類です。
データ取得と分析：データのある場所につなぎ、問い合わせ方を示す。
業務プロセスとチームの自動化：朝会の更新の投稿、週次まとめの作成など。
コードの雛形とテンプレート：あるタイプのアプリの土台を用意する。
コード品質とレビュー：チームのコーディング基準を守る。
CI/CD とデプロイ：コードの取得、プッシュ、デプロイ。
ランブック：症状（アラート、エラーメッセージ）を受け取り、構造化された調査報告を書く。
インフラ運用：定期メンテナンス。破壊的な操作の前にはガードレールを置く。

コードを書かない人は、3、4、8 から始めることが多いです。

ステップ 2：わかりきったことは書かない

skill には、Claude をいつものやり方の先へ押し出す内容を入れます。たとえば Anthropic のフロントエンドデザイン skill は、Inter フォントや紫のグラデーションのようなありがちなパターンから Claude を引き離すためにあります。

ステップ 3：「Gotchas（落とし穴）」セクションを書く

元記事はこれを、どの skill でもいちばん情報価値の高い部分と呼んでいます。AI がつまずきやすい点を書き、時間とともに足していきます。元記事の例：サブスクリプションのテーブルは追記専用なので、欲しい行は作成日が最新の行ではなく、バージョン番号がいちばん大きい行です。

## Gotchas
- [AI が間違えやすいこと] → [正しいやり方]
- [2 つのシステムで名前が違う項目] → [どちらが正しい項目か]

ステップ 4：フォルダで分け、必要な時だけ読ませる

すべてを 1 つのファイルに詰め込まないこと。テンプレートは assets/、参考資料は references/、スクリプトは scripts/ に置き、SKILL.md から必要な時に正しいファイルへ案内します。これを段階的な開示（progressive disclosure）と呼びます。AI は関係する部分だけを読むので、作業メモリを節約できます。

ステップ 5：目標を伝え、一歩ずつ縛らない

6 つの git コマンドを並べる代わりに、元記事は目標を書くことを勧めています。例：「このコミットをきれいなブランチに cherry-pick してください。衝突は元の意図を保って解決してください。」情報と制約は渡しつつ、Claude に柔軟さを残します。

ステップ 6：初期設定を考えておく

設定（どの Slack チャンネルか、どのデータテーブルか）は skill の config.json に保存します。未設定なら、Claude にわかりやすい選択肢で利用者に聞かせます。

ステップ 7：説明文は人ではなく AI に向けて書く

説明（description）は要約ではありません。Claude がその skill を使うかどうか決めるための文なので、利用者がよく言う言葉を入れます。元記事の例：

description: PR がマージされるまで見守る。
「見ておいて」「CI を見張って」「ちゃんと入るようにして」と言われたら使う。

ステップ 8：Claude に覚えさせ、スクリプトを再利用させる

追記専用のログファイル（例：${CLAUDE_PLUGIN_DATA} 変数が指すフォルダに置く）があれば、Claude は前回何をしたかを覚えていられます。
skill に補助関数を入れ、落とし穴を関数の説明に書いておけば、Claude は決まり文句のコードを一から書き直さず、組み合わせて使えます。

ステップ 9：skill を呼んだ時だけガードレールを付ける

skill は使われている間だけ hook（自動チェック）を有効にできます。Anthropic の例：/careful は本番環境での作業中に危険なコマンドを止め、/freeze は編集できるフォルダを限定します。

結果の例

すっきりした「週報」skill は次のようになります：

.claude/skills/weekly-report/
├── SKILL.md          # 目標、主な手順、Gotchas
├── config.json       # 報告の送り先、使うデータテーブル
├── references/
│   └── metrics.md    # 各指標の意味
└── assets/
    └── template.md   # 報告のテンプレート

SKILL.md の説明：「売上データから週報を書く。『週報』『今週のまとめ』『weekly recap』と言われたら使う。」Gotchas には「売上は注文日ではなく支払日で数える。」と書きます。

もっと良くするコツ

小さく始める。 元記事の結論は、彼らの最良の skill の多くが数行と 1 つの落とし穴から始まり、Claude が新しいケースに当たるたびにみんなが書き足して良くなった、というものです。
共有の仕方を選ぶ。 小さなチームはリポジトリ（.claude/skills）に置き、大きなチームはプラグインのマーケットプレイスを作って各自が選んで入れます。
どの skill が使われているか測る。 Anthropic は hook で skill の利用を記録し、人気の skill と、期待より呼ばれていない skill を見つけています。
CLAUDE.md、Claude にすべてを覚えさせる指示書も読んで、何を CLAUDE.md に置き、何を skill に分けるか決めましょう。