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

「なんとなく使っているだけ」で終わっていませんか

Claude Codeを毎日触っているものの、毎回同じ指示を一から書き直している、チームメンバーごとにやり方がバラバラで再現性がない……そんな悩みを抱えている方は多いのではないでしょうか。最近はSNS上で、エンジニアたちが自分の.claude/skillsをGitHubで公開する動きが目立つようになりました。中身を覗いてみると「なるほど、こう書けば良いのか」と発見がある一方で、いきなり真似しようとすると構成に戸惑うことも少なくありません。

この記事の結論：Skillsの型を知れば、今日から自作できる

この記事では、Claude Code Skills（Agent Skills）の基本的な仕組みと、公開されているSkillsに共通する「良い書き方」の考え方を整理し、実際に自分専用のSkillを1つ作れるところまでを手順化します。読み終える頃には、SKILL.mdを白紙から書けるようになっているはずです。

手順1：Skillsの仕組みを最低限理解する

Claude Code Skillsは、プロジェクト内の.claude/skills/というディレクトリ配下に、スキルごとのフォルダを作り、その中にSKILL.mdというファイルを置く構成が基本です。SKILL.mdはYAML形式のフロントマター（名前や説明など）と、Markdown本文で構成されており、必要に応じて参考資料やスクリプトなどの追加ファイルを同じフォルダ内に置くこともできます。

ここで重要なのが「段階的開示」という考え方です。常時読み込まれるのは名前と説明の部分だけで、実際にそのタスクが発生したときに本文や追加ファイルが読み込まれる、という設計思想があります。つまり最初の説明文（description）の書き方が、そのSkillが「使われるかどうか」を左右する肝になるわけです。

Skillsの本質は「Claudeに何をしてほしいかの手順書」であり、人間の新人に引き継ぎ資料を渡す感覚に近いものです。

Claude Codeを安全に実行する環境構築についてはこちらも参考にしてください → Claude Code・Codexを安全に動かす爆速サンドボックス構築ガイド

手順2：公開されているSkillsの共通点を観察する

本格的に作り始める前に、すでに公開されているSkillsを何本か眺めてみることをおすすめします。良いSkillsには、いくつか共通する傾向があります。

• 説明文（description）が具体的で、「いつ使うべきか」が一文で分かる
• 本文がタスクの手順として書かれており、抽象的な心構えで終わっていない
• 1つのSkillが1つの役割に絞られていて、あれもこれも詰め込んでいない

正直なところ、最初にいくつかのSkillsを見たときは「これくらいシンプルでいいのか」と少し驚きました。凝った構成よりも、目的がはっきりしていることの方がずっと重要だと感じます。

手順3：自分のSkillの「役割」を1つに絞って決める

最初から複数の機能を持たせたくなる気持ちは分かりますが、ここは我慢が必要です。まずは自分の業務の中で「毎回同じ手順を繰り返している作業」を1つだけ選びましょう。たとえば「週報のフォーマット整形」「コードレビュー時のチェック観点の確認」など、範囲が狭いものほど最初の一歩としては適しています。

手順4：.claude/skills/にフォルダとSKILL.mdを作る

実際の作業に入ります。プロジェクトのルートに.claude/skills/というディレクトリがなければ作成し、その下にスキル名のフォルダ（例：weekly-report/）を作ります。フォルダ内にSKILL.mdを新規作成し、フロントマターに名前と説明を記述します。説明文は「このSkillが何をするためのものか」「どんな場面で呼ばれるべきか」を、他のSkillと混同しない粒度で書くのがコツです。

本文には、実際の作業手順を箇条書きやステップ形式で書いていきます。抽象的な指示よりも、「まず〜を確認する」「次に〜の形式で出力する」といった、行動レベルの記述が有効です。ここは正直、最初は「どこまで細かく書けばいいのか」で手が止まりやすいポイントです。迷ったら、自分が新人に口頭で説明するときの手順をそのまま書き出してみると、案外うまくまとまります。

手順5：小さく試してから育てていく

一度で完璧なSkillを作ろうとせず、まずは短い本文で動かしてみて、実際の応答を見ながら足りない指示を追記していくやり方が、個人的には楽でした。追加の参考資料や補足ファイルが必要になったら、同じフォルダ内に置いていけば十分です。プロジェクト単位だけでなく、ユーザー単位でも配置できる仕組みがあるため、個人的によく使う手順は自分の環境側に、チームで共有したい手順はリポジトリ側に置く、という使い分けを意識すると整理しやすくなります。

つまずきやすいポイントと対処

• descriptionを後回しにしてしまう：本文の作成に集中しすぎて説明文が雑になり、Skillが呼び出されないケースがあります。descriptionは本文より先に、丁寧に書くくらいの意識で良いと思います。
• 1つのSkillに機能を詰め込みすぎる：範囲が広がるほど汎用的に見えますが、実際には呼び出し判断が難しくなります。分割できそうな部分は、思い切って別のSkillに切り出しましょう。
• 公開されているSkillsをそのままコピーして満足してしまう：構成の参考にするのは有効ですが、自分の業務フローに合わせて手順部分は必ず書き直す必要があります。

まとめ：まずは1つ、狭い範囲のSkillから

良いClaude Code Skillsに共通するのは、役割が1つに絞られていて、descriptionと手順が具体的に書かれていることです。公開ラッシュで話題になっているSkillsも、構成自体はシンプルなものが多く、真似しやすい部分が多いのが実際のところです。まずは自分の業務の中から狭い範囲のタスクを1つ選び、SKILL.mdを書いてみることから始めてみてはいかがでしょうか。育てていくうちに、自分だけの「引き継ぎ資料集」が自然と積み上がっていくはずです。