Claude Codeスキルの作り方｜SKILL.mdは"新人への引き継ぎ書"だと思って書く

この記事でわかること

Claude Codeのスキル（SKILL.md）は、作るだけなら10分で終わる。フォルダを作って、frontmatterを書いて、手順を並べれば動く。

問題はそこじゃない。作ったスキルが発動しない・思った通りに動かない・そのうち使わなくなる。自分も約20本のスキルを自作して運用する中で、この3つ全部を踏んだ。

先に結論。スキルがうまく回り始めたのは、書き方のテクニックを覚えたときじゃなくて、「SKILL.mdは新人への引き継ぎ書だ」と思って書くようにしたときだった。この記事では、作り方の3ステップを最短で押さえたあと、引き継ぎ書として設計する話と、20本運用して分かった「効くスキルと死ぬスキルの差」を書く。

記事概要図

スキルの作り方は3ステップで終わる

まず最短ルートだけ押さえる。

フォルダを作る：.claude/skills/スキル名/ （プロジェクト用）または ~/.claude/skills/スキル名/（全プロジェクト共通）
SKILL.mdを書く：frontmatterに name と description、本文に手順
動作確認する：Claude Codeに該当する頼み方をして、スキルが発動するか見る

---
name: my-skill
description: このスキルが「いつ」使われるべきかを書く
---

ここに手順や判断基準を書く

仕様の詳細は公式ドキュメントにまとまっているので、ここでは繰り返さない。むしろ最初の1本は、仕様を読み込むよりClaude Code自身に「◯◯するスキルを作って」と頼んで叩き台を作らせるほうが早い。自分もほぼ全スキルをこの方式で作っている。

で、ここからが本題。この3ステップ通りに作ったスキルの何本かは、数週間後に使われなくなっていた。

書き方より先に決めること：誰に引き継ぐつもりで書くか

自分はSE/PMの仕事で、手順書や引き継ぎ書を書く側だった。手順書を作る時にいつも置いている基準は一つで、「作業者が変わっても同じ成果になるか」。そのためには「実施する作業」だけじゃなく、「実施した結果がどうなっていれば正しいか」までセットで書く必要がある。手順だけの手順書は、書いた本人しか正しく実行できない。

とはいえ、これが常にできるかというと現実は厳しい。連日の本番作業が続く局面では、手順書の作成にもレビューにも十分な時間が取れず、品質が下がる。だから余裕のあるうちに汎用的な雛形を作っておいて、「作業者が変わっても同じ成果になる書き方」をあらかじめプロセスとしてルール化しておく。余裕がある時や簡単な作業のうちにメンバとプロセスを合意しておく——というのが実務でたどり着いた運用だった。

SKILL.mdは、この構造にきれいに重なる。Claude Codeは毎回まっさらな状態で仕事を始める新人で、SKILL.mdだけが引き継ぎ書。スキルを書く行為は「余裕のあるうちに雛形を作っておく」ことそのものだ。だから手順のほかに、次の4つを書くようになった。

引き継ぎ書の要素	SKILL.mdでの書き場所	書かないとどうなるか
いつこの仕事が発生するか	frontmatterの`description`	スキルが発動しない（作ったのに使われない）
完了条件（何がどうなっていれば成功か）	本文の検証・完了条件	「できました」の報告を検証できない・毎回結果がぶれる
迷った時のデフォルト	本文の判断基準	毎回違う判断をされる・確認質問が増える
やらないこと	本文の禁止事項	頼んでいない「善意の余計な作業」をされる

とくにdescriptionは、スキルの中身の要約ではなくて**「いつ発動すべきか」のトリガー定義**として書く。ここを「◯◯を管理するスキル」みたいな名詞の説明で書くと発動しない。「ユーザーが『◯◯して』『◯◯を確認』と言ったら起動」のように、引き金になる状況・言葉を書く。

20本運用して分かった、効くスキルと死ぬスキルの差

自分のリポジトリには現在、自作・翻訳あわせて約20本のスキルがある。ブログ運用・投資の定点観測・YouTube統計・デバッグ・LP監査など用途はバラバラ。並べてみると、生き残っているスキルには偏りがあった。

生き残っているスキル（毎週〜毎日使う）

スキル	用途	生きてる理由（推定）
weekly-check	週次の事業分析レポート	毎週決まって発生する仕事だから
task-check	今日やるべきTop3の提示	毎回の作業開始時に呼ぶから
publish-article	記事の安全公開（ビルド→diff→公開）	事故ると被害が大きい作業の安全装置だから
incident	ブログ障害対応の8ステップ	緊急時に頭が真っ白でも手順が回るから
bug-hunt	デバッグの型（推理より先に判定コマンド）	「勘で直す」への逆戻りを防ぐから

死んだ（統合された）スキルの実例

daily-checkという「毎朝のタスク確認」スキルを作っていたが、先日task-checkに統合して廃止した。毎朝用と単発確認用で2本に分かれていたけど、やることがほぼ同じで、どっちを呼ぶか自分が迷うようになったから。スキルが増えてくると「Claudeが迷う」より先に「人間が迷う」。

この経験から、いまは新しいスキルを作る前に「既存スキルの拡張で済まないか」を先に考えるようになった。

生きてるスキルの共通点を一言でいうと、**「定期的に必ず発生する仕事」か「事故を防ぐ安全装置」**のどちらか。逆に「たまに使うと便利そう」で作ったスキルは、存在自体を忘れて死ぬ。人間の新人教育と同じで、月1回しか発生しない仕事の引き継ぎ書は、書いても読まれない。

つまずきやすいポイント3つ

作り始めてから引っかかりやすい点を、先回りで3つ。

① descriptionを盛りすぎると逆に発動しない

あれもこれもとトリガー条件を足していくと、かえって「いつ使うか」がぼやけて発動率が下がる。1スキル1仕事に絞って、descriptionは「この状況・この言葉で起動」を短く書くほうが安定する。うまく動かない時にdescriptionの書き方が原因だったという報告は多くて、YAMLのコロンでパースが壊れていた事例のような構文レベルの罠もある。発動しない時は、まず中身よりfrontmatterを疑う。

② 参照ファイルの置き場所とパス

手順が長くなるならSKILL.mdに全部書かず、同じスキルフォルダに参照ファイルを分けて置ける。ただしパスの解決は環境によって癖があるので、最初は「SKILL.md1枚＋スキルフォルダ内の相対参照」のシンプル構成から始めるのが無難。

③ 粒度の迷い（1本にまとめるか、分けるか）

判断基準はシンプルで、呼ぶタイミングが同じなら1本、違うなら分ける。daily-checkとtask-checkを統合したのは、呼ぶタイミング（作業を始める時）が同じだったから。逆に、記事執筆と記事公開は連続する仕事だけどタイミングが違うので別スキルのままにしている。

作って終わりにしない：スキルは監査して育てる

引き継ぎ書は書いて終わりじゃなくて、現場が変わったら書き直す。スキルも同じで、モデルが世代交代したタイミングで全スキルを棚卸しした話を前に書いた。新モデルに監査させたら、4本中2本は「直すな」と返ってきた、という顛末。

他人の作ったスキル集を導入して選別する話（星11万のskills集から3つ抜いた）、外部ツールをスキル化する話（notebooklm-pyのスキル化）、Obsidianの作法をスキルで教える話（obsidian-skills導入ガイド）も書いているので、実例が見たい人はどうぞ。

3つの結論

作り方は3ステップ・最初の1本はClaudeに作らせる。仕様の勉強から入らない
SKILL.mdは引き継ぎ書。基準は「作業者が変わっても同じ成果になるか」。手順のほかに「いつ発動するか」「完了条件」「迷った時のデフォルト」「やらないこと」を書く
「定期的に発生する仕事」と「安全装置」だけスキル化する。「あると便利そう」は死ぬ。増えたら統合を考える

Claude Codeの活用を体系的に学ぶなら、UdemyのAI活用系コースも選択肢。セール時（1,500〜2,000円）が狙い目。

Udemyで講座を探す（セール時が狙い目）