Claude Code Skill を効かせる9つのコツ

Claude Code に同じ指示を何度も打ち込んでいて、「これ、前にも説明したな」と感じたことはないでしょうか。「このリポジトリのテストはこのコマンドで動かす」「デプロイはこの手順を踏む」「この API の認証まわりは少しクセがある」といった、そのチームでしか通じない知識です。こうした知識を Claude に持たせる仕組みが Skills です。

Anthropic が「Lessons from building Claude Code: How we use skills」という記事を公開しています。Claude Code を開発しているチーム自身が、社内で数百の Skills を運用する中で見えてきた知見をまとめたものです。

claude.com

本記事では元記事のうち、Skills を実際に作って効かせるための実践的なコツに絞って紹介します。すでに Claude Code を日常的に使っていて、これから自分やチームの知識を Skill にしていきたい、という方を想定しています。まずは Skill の概要を簡単におさらいしてから、作り方のコツに入ります。

そもそも Skills とは

Skills は「ただのマークダウンファイル」だと思われがちですが、実際はそうではありません。Skills は指示・スクリプト・リソースをまとめたフォルダであり、Claude がその場の文脈に応じて発見し、使えるようにしたものです。

フォルダの起点になるのが SKILL.md というファイルです。ここに何をする Skill なのかと使い方を書き、必要に応じて同じフォルダ内の別ファイル（API の詳細な仕様、出力テンプレート、補助スクリプトなど）を参照させます。設定ファイルやフックを同梱することもできます。

実物のイメージを持っておくと、このあとのコツが理解しやすくなります。最小の SKILL.md はこの程度です。

---
name: billing-queries
description: 課金データを SQL で集計するときに使う。subscriptions テーブルや
  支払い状態を扱うクエリを書く場面で参照する。
---

## 概要
課金まわりのデータを集計するときの注意点をまとめた Skill です。

## ハマりどころ
- `subscriptions` テーブルは追記専用です。最新の状態は version が
  最大の行であり、`created_at` が最新の行ではありません。

## 詳細なテーブル定義
references/schema.md を参照してください。

このように SKILL.md に概要や使い方を書き、詳細は references/ などの別ファイルに分けて Skill を組み立てます。この「ただのテキストではなくフォルダである」という点が、後半のコツを理解する前提になります。

よく効く Skill を書くコツ

ここからは、Skill を効かせるための具体的なコツに入ります。元記事に挙げられた9つを、実務で効きやすい順に並べ替え、「何を書くか」「どう構造化するか」「どう動かすか」の3つのグループに分けて紹介します。

何を書くか

1. 当たり前を書かない

最初のコツであり、おそらく一番大事な原則です。Claude がデフォルトで普通にやることを Skill に書いても、文脈（コンテキスト）を消費するだけで価値が増えません。書くべきなのは、Claude の判断を変える情報だけです。

例として挙げられているのが、フロントエンドの画面デザインを Claude に任せるときの Skill です。この Skill が教えているのは、デフォルトのままだと出がちな「Inter フォント」や「紫のグラデーション」を避ける、といったデザインの好みです。Claude が放っておいてもやることではなく、放っておくと外す方向に作用する知識を渡している、というわけです。

Skill を書き始めると、つい丁寧に網羅したくなります。ですが「これは書かなくても Claude はやるな」と思った行は、思い切って削ったほうが Skill は効きます。

2. ハマりどころこそ最重要

ハマりどころ（原文では gotchas）とは、仕様を読んだだけでは気づけず、知らないと確実にハマる、その環境ならではのクセのことです。Skill の中で最も効きやすいのは、こうしたハマりどころをまとめたセクションだと指摘されています。チームのメンバーが新人に「ここ、引っかかるから気をつけてね」と伝えるような知識であり、Claude が学習データから知りようがない情報です。

挙げられている例を見ると、それが何を指すのかがよく分かります。

「subscriptions テーブルは追記専用（append-only）です。欲しい行は version が最大のものであって、created_at が最新のものではありません」
「このフィールドは API ゲートウェイでは @request_id、課金サービスでは trace_id と呼ばれます。同じ値です」
「Stripe の Webhook が実際には処理されていなくても、ステージングは 200 を返します。本当の状態は payment_events を見てください」

どれも、知らなければ Claude があっさり間違える類の知識です。最新の行を取ってきて誤る、別名のフィールドを別物だと解釈する、200 が返ったから成功したと判断する。こうした「もっともらしい誤り」を未然に防ぐのが、ハマりどころを書く狙いです。Skill を作るなら、まずチームの暗黙知をここに書き出すのが手っ取り早いです。

どう構造化するか

3. ファイルシステムと段階的開示を使う

Skills がフォルダであることが効いてくるのがこのコツです。すべてを SKILL.md に詰め込むのではなく、ファイルを分けて整理し、必要なときだけ参照させます。これを段階的開示（progressive disclosure）と呼びます。

たとえば次のように構成します。

references/api.md：関数シグネチャなど詳細な仕様。実装時にだけ読ませる
assets/：出力に使うテンプレートファイル
stuck-jobs.md：ジョブが詰まったときにだけ参照させる手順

SKILL.md には概要と「どんなときにどのファイルを見るか」を書いておき、詳細は別ファイルに逃がす。こうすると、普段は軽い情報だけを読み込み、本当に必要になった場面で詳細を開く、という動きになります。コンテキストを節約しつつ、いざというときの情報量も確保できます。

4. レールを敷きすぎない

情報は十分に渡しつつ、Claude が状況に応じて判断する余地は残す。これが、レールを敷いて強制する（railroading）のを避ける、というコツです。

手順を1から10までガチガチに固定すると、想定どおりの状況では動きますが、少しでも外れた途端に破綻します。必要な前提と注意点は渡したうえで、具体的なやり方は Claude に委ねる。Skill は「マニュアル」よりも「先輩が渡すメモ」に近いものとして書くと、応用が効きます。

5. description はモデル向けに書く

Skill の description（説明文）は、人間向けの要約ではありません。Claude がどの Skill を呼ぶかを判断するためのトリガーです。ここを取り違えると、せっかく作った Skill が必要な場面で呼ばれません。

コツは、ユーザーが実際に使いそうなトリガー語を description に含めることです。たとえば本番のエラーを調査する Skill の説明には、ユーザーが実際に使う「調査して」「原因を調べて」といった語を入れておきます。人間に向けた整った説明文を書くのではなく、「この言葉が出てきたらこの Skill」とモデルが結びつけられる語を意識して入れる、という発想です。

どう動かすか

6. セットアップを設計する

Skill によっては、使う前にユーザー固有の設定が要ります。接続先のクラスタ名、利用するデータソースの ID などです。こうした設定は config.json に保存しておきます。

うまく作られた Skill は、設定が見つからないときに勝手に失敗するのではなく、ユーザーに設定を尋ねます。その際に使えるのが AskUserQuestion ツールです。これは「どのクラスタを使いますか」といった質問を、自由記述ではなく選択肢の形でユーザーに提示するためのツールです。ユーザーは選ぶだけで済み、Claude 側も回答を構造化された値として受け取れるので解釈に迷いません。設定が足りないときに黙って失敗するのではなく、こうして対話的に補える Skill は、初回セットアップの体験がスムーズになります。

7. Claude に状態を覚えさせる

Claude は基本的にセッションをまたいで記憶を持ちません。そこで、覚えておいてほしい状態は追記ログや JSON ファイルに書き出させます。

たとえば朝会の投稿を作る Skill であれば、standups.log のようなログファイルを持たせ、過去の投稿内容を参照できるようにしておきます。前回何を書いたかが分かるので、毎回ゼロから作らずに差分を意識した投稿ができます。

8. スクリプトを同梱してコードを生成させる

定型処理は、Claude にその場で書かせるのではなく、Skill にコードライブラリとして同梱しておきます。すると Claude は定型コードの記述から解放され、それらをどう組み合わせるかに集中できます。

さらに、用意したライブラリを部品として Claude がその場でスクリプトを生成し、より高度な分析を組み立てる、という使い方もできます。土台を渡しておくほど、Claude は応用に頭を使えるようになります。

9. オンデマンドフックでガードレールを張る

Skill には、その Skill が呼ばれたときにだけ有効になり、セッションの間だけ持続するフックを仕込めます。常時有効ではなく、必要な作業のときだけ効くガードレールです。

例として2つ挙げられています。

/careful：rm -rf、DROP TABLE、force-push、kubectl delete といった破壊的なコマンドを PreToolUse でブロックする
/freeze：特定のディレクトリの外への Edit / Write をブロックする

危険な操作を含む作業をするときだけこうしたフックを効かせておけば、事故を未然に防げます。Skill は知識を渡すだけでなく、ふるまいに制約をかける手段にもなる、というわけです。

配布と運用

作った Skill をチームに広げる方法は大きく2つあります。1つはリポジトリの ./.claude/skills にチェックインする方法。もう1つはプラグインマーケットプレイスを作る方法です。小さなチームなら前者で十分機能しますが、規模が大きくなると、ユーザーが使う Skill を選べてセットアップの導線も用意できるマーケットプレイス方式が適しています。

運用面で印象的なのは、Anthropic 社内に中央の承認チームが存在しないという点です。誰かが便利な Skill を作ってサンドボックスにアップロードし、Slack で広める。使われて定着したものが、PR を通じてマーケットプレイスに昇格する。トップダウンの審査ではなく、有用なものが自然に広がっていく仕組みです。

Skills は互いに依存・合成できる点も触れておく価値があります。ある Skill が別の Skill を名前で参照しておくと、それがインストールされていればモデルが呼び出します。たとえば CSV を生成する Skill が、ファイルアップロードの Skill に依存する、といった組み合わせです。小さな Skill を組み合わせて大きな仕事をさせる、という発想ができます。

最後に計測です。Anthropic では PreToolUse フックを使って全社の Skill 利用状況をログに記録しています。これにより、よく使われている Skill を把握できるだけでなく、本来呼ばれるべき場面で呼ばれていない未発火（undertriggering）も検知できます。前述の「description はモデル向けに書く」が効いているかどうかを、データで確かめられるわけです。

まとめ

Skill 作りで一番大事な原則は、最初に挙げたコツ「当たり前を書かない」に尽きると感じました。Claude のデフォルトの判断を変える情報だけを渡す、ということです。当たり前を書かず、その環境固有のハマりどころを書く。これが Skill を効かせる決め手です。

裏を返せば、立派な Skill をいきなり作る必要はないです。まずは自分の業務で「Claude がいつも同じところで間違えるな」と感じる落とし穴を1つ、ハマりどころとして書き出してみる。これだけでも Claude の動きは変わります。そこから段階的開示で情報を整理したり、フックでガードレールを張ったりと、必要に応じて育てていけばよいのだと思います。

何から作るか迷うなら、もう一つヒントがあります。元記事によれば、Anthropic 社内で Claude の出力品質に最も効いたのは、書いたコードが本当に動くかを確かめる検証系の Skill だったそうです。コードを書かせるだけでなく、その結果を確かめさせる。この一手間を Skill にするのは有力な選択肢です。

参考

anthropics/skills（Anthropic 公開のサンプル Skill 集） https://github.com/anthropics/skills