有名エンジニアの .claude/skills 公開ラッシュから学ぶ、良い Claude Code Skills の書き方

Claude Codeを毎日使っているのに、毎回同じ指示を一から書いている。チームのメンバーごとに頼み方がバラバラで、結果もそろわない。そんな悩みを解決するのがSkills（スキル）です。最近は、エンジニアが自分の .claude/skills をGitHubで公開する動きも広がっています。

タクヤ

ポイントは「いつ使うかが分かる説明文」と「1つに絞った役割」です。公式ドキュメントの仕様に沿って、実際に1つ作ってみましょう。

Skillsの仕組み

Skillは、Claudeに渡す「手順書」です。新人に渡す引き継ぎ資料のようなものだと考えると分かりやすいでしょう。

大事なのは、読み込まれるタイミングです。

• 説明文（description）：いつも読み込まれていて、Claudeが「このSkillを使うべきか」の判断に使う
• 本文（手順）：Skillが呼ばれたときに初めて読み込まれる
• 補足のファイル：本文から参照されていて、必要になったときだけ読み込まれる

つまり、説明文が雑だと、どれだけ良い手順を書いても使われません。逆に、本文や資料をたくさん置いても、呼ばれるまでは使用量を消費しにくい作りになっています。

Skillを置く場所

自分だけがよく使う手順は個人用に、チームで共有したい手順はプロジェクト用に置くと整理しやすくなります。

実際に1つ作ってみる

公式ドキュメントにある「変更内容をまとめるSkill」を例に作ってみます。

1. フォルダを作る：~/.claude/skills/summarize-changes/
2. その中に SKILL.md を作り、次の内容を書く

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

これで、Claude Codeに「何を変えたっけ？」と聞くと自動でこのSkillが使われ、/summarize-changes と打てば自分から呼ぶこともできます。

よく使う設定項目（frontmatter）

SKILL.mdの先頭の --- で囲んだ部分で、Skillの動きを設定できます。1行目が --- でないと、全体が本文として扱われるので注意しましょう。

引数は、本文の中で $ARGUMENTS（すべて）や $0・$1（順番で指定）として使えます。たとえば /fix-issue 123 と打てば、$ARGUMENTS が「123」に置き換わります。

タクヤ

デプロイやメール送信など、勝手に実行されると困るSkillには、必ず disable-model-invocation: true を付けておきましょう。

良いSkillを書くコツ（公式のベストプラクティス）

1. 説明文は短く具体的に：ユーザーが実際に言いそうな言葉（「何を変えた？」「コミットメッセージ作って」など）を入れる。説明文は、追加の説明と合わせて1,536文字で切られる
2. 「今回だけ」ではなく「ずっと有効な指示」を書く：Skillの内容は、呼ばれたあともその会話に残り続ける。「今回はテストを実行して」ではなく「変更のたびに〜を確認する」と書く
3. SKILL.mdは500行以内に：詳しい資料は reference.md などの別ファイルに分け、SKILL.mdからリンクする
4. 役割は1つに絞る：いろいろ詰め込むと説明文があいまいになり、結局呼ばれなくなる
5. 使われていないSkillは消す：/skill-doctor で、それぞれのSkillがどれくらい使われ、どれくらい容量を使っているかを確認できる

Claude Codeを安全に動かす環境づくりは、Claude Code・Codexを安全に動かす爆速サンドボックス構築ガイドで解説しています。

つまずきやすいポイント

よくある質問

まとめ

良いClaude Code Skillは、説明文に「何をするか」と「いつ使うか」が書かれていて、役割が1つに絞られているものです。SKILL.mdは短く保ち、詳しい資料は別ファイルに分けましょう。

まずは上の「変更内容をまとめるSkill」をそのまま作って動かし、自分の作業に合わせて書き換えるところから始めてみてください。