ai-docs

Lessons from building Claude Code: How we use skills

Properties1
tagsskills, claude-code, context-engineering, plugins

原典: Lessons from building Claude Code: How we use skills

一行要約

Anthropic 社内の数百の skill は9種類に分かれ、1種類にきれいに収まるものが最も良い。書くときは当たり前を書かず、落とし穴（Gotchas）の節を育て、ファイルの木で段階的に開示し、description は人向けの要約ではなく発火条件として書く。

要点

skill は markdown ではなくフォルダ

A common misconception we hear about skills is that they are “just markdown files.” They’re actually folders that can include scripts, assets, data, etc. that the agent can discover, explore and manipulate.

よくある誤解は、skill が「ただの markdown ファイル」だというものだ。実際にはフォルダで、エージェントが見つけ、探り、操作できるスクリプト・アセット・データなどを含められる。

9つの種類

The best skills fit cleanly into one; the ones that try to do too much straddle several and confuse the agent.

最も良い skill は1つの種類にきれいに収まる。やりすぎようとするものは複数にまたがり、エージェントを混乱させる。

種類中身と例
1. ライブラリと API のリファレンス社内外のライブラリ・CLI・SDK の正しい使い方。参照コード片と、書くときに避ける落とし穴の一覧
2. 製品の検証コードが動くことを確かめる方法（playwright、tmux など）。社内で Claude の出力品質に最も測れる効果があった。エンジニアが1週間かけて磨く価値がある（何を試したかの動画を録らせる、各段で状態を assert する）
3. データの取得と分析データと監視の基盤につなぐ（資格情報つきの取得ライブラリ、ダッシュボード ID、よくある手順）
4. 業務プロセスとチームの自動化繰り返しの作業を1コマンドに。前回の結果をログに残すと、一貫性と振り返りに効く
5. コードの雛形フレームワークの雛形。コードだけでは表せない自然言語の要件があるときに特に
6. コード品質とレビュー決定的なスクリプトで堅く。hook や GitHub Action で自動で走らせる
7. CI/CD とデプロイ取得・push・デプロイ。他の skill を参照してデータを集める
8. runbook症状（Slack のスレッド、アラート、エラーの痕跡）から複数ツールの調査をして、構造化された報告を出す
9. インフラ運用定型の保守。破壊的な操作を含むものはガードレールに助けられる

書き方のコツ

  • 当たり前を書かない —— Claude はコードを書けるし、コードベースを読める。既定でやることを繰り返す skill は、価値を足さずに context を足す。知識の skill なら、Claude を普段の考え方から押し出す情報に絞る（frontend design skill は Inter フォントや紫のグラデーションのような定番を避けさせる）
  • Gotchas の節を作る

The highest-signal content in any skill is the Gotchas section. These sections should be built up from common failure points that Claude runs into when using your skill.

どの skill でも最も信号の強い内容は Gotchas の節である。 この節は、skill を使うときに Claude がよく失敗する点から積み上げていくものだ。

  • ファイルシステムと段階的な開示 —— skill にどんなファイルがあるかを伝えれば、適切なときに読む（詳細な関数のシグネチャは references/api.md、出力のテンプレートは assets/）
  • Claude を一本道に縛らない —— 再利用されるものなので、具体的すぎる指示に注意する。目的と制約を言い、すべての手順は言わない
  • 初期設定を考える —— Slack のチャンネルのように利用者からの情報が要るなら、skill のディレクトリの config.json に置き、未設定ならエージェントに聞かせる（選択肢の形なら AskUserQuestion）
  • description はモデル向けに書く

When Claude Code starts a session, it builds a listing of every available skill with its description. This listing is what Claude scans to decide “is there a skill for this request?” Which means the description field is not a summary, it’s a description of when to trigger this skill.

Claude Code はセッションの開始時に、使えるすべての skill を description つきで一覧にする。Claude はこの一覧を見て「この依頼に合う skill はあるか」を決める。つまり description は要約ではなく、いつこの skill を発火させるかの説明である。

  • 記憶させる —— 追記だけのログ、JSON、SQLite に自分の履歴を残させる（standup の skill が standups.log を読めば、昨日から何が変わったかが分かる）。安定した保存先は ${CLAUDE_PLUGIN_DATA}
  • スクリプトを置き、コードを生成させる —— 補助関数の小さなライブラリ（落とし穴を docstring に書く）を渡すと、Claude はターンを定型の再構築ではなく組み立てに使い、その場の問いに合わせて一回限りのスクリプトを書く
  • 呼んだときだけの hook —— skill を呼んだときにだけ有効になり、セッションの間だけ続く。常時は要らないが時々とても効く強い hook に使う（/careful: Bash の PreToolUse matcher で rm -rf・DROP TABLE・force-push・kubectl delete を止める。本番に触ると分かっているときだけ。/freeze: 特定のディレクトリ以外への Edit / Write を止める）

配る・測る

  • 小さなチームで少ないリポジトリなら、./.claude/skills にコミット。ただしコミットした skill はどれも少しずつ context を足すので、規模が大きくなったら社内の plugin marketplace で配り、入れるかを各自に選ばせる
  • marketplace に何を入れるかを決める中央のチームは無い —— GitHub のサンドボックスフォルダに上げて Slack で紹介し、広まったら（判断は持ち主）PR で marketplace に移す
  • skill どうしの依存は、まだ marketplace や skill の機能として無い —— 他の skill を名前で参照すれば、入っていればモデルが呼ぶ
  • 測る —— 社内では PreToolUse hook で skill の使用を記録し、人気のものや期待より発火していないものを見つける

Most of our best skills began as a few lines and a single gotcha, then got better because people kept adding to them as Claude hit new edge cases.

最も良い skill の多くは、数行と1つの落とし穴から始まり、Claude が新しいエッジケースに当たるたびに人が足していったことで良くなった。

そのまま使える具体例

Gotchas の書き方の例（原典）:

The subscriptions table is append-only. The row you want is the one with the highest version, not the most recent created_at.
This field is called @request_id in the API gateway and trace_id in the billing service. They're the same value.
Staging returns 200 even when the Stripe webhook didn't actually process. Check payment_events for the real state.

呼んだときだけの hook の例: /careful（本番に触るときだけ破壊的なコマンドを止める）、/freeze（デバッグ中に、決めたディレクトリ以外の編集を止める）。

原典で言及されている関連文書

  • skills — skill の設定項目

バックリンク