「Claude Code の Skills、使ってみたいんですけど、skill.md って結局どう書けばいいんですか？」という質問を、もう何度もらったかわかりません。そしてそのたびに、私はだいたい同じことを返しています。
frontmatter の仕様書を熟読する必要はありません。Claude Code に「これ skill 化して」と頼めばいい。
これ、手抜きに見えますか？ でも、本当に一番実務的で、一番速いんです。現時点で私たちは 95 個以上の Skill を運用していますが、そのほとんどは「仕様を読んでから書いた」ものではなく、「作業を何度かやってから Claude に skill 化してもらった」ものでした。この記事では、なぜその順序が正しいのか、そして作った後に本当に気をつけるべきことを、実運用のエピソードと一緒に整理します。
設計思想や運用ノウハウをもっと踏み込んで知りたい方は、Claude Code Skills 入門ガイド、Skills 設計パターン上級編、ポータブル資産にする設計 にまとめています。本記事を読み終えたら、順に目を通してみてください。
この記事で扱うこと
skill.md（正式にはSKILL.md）の最小構成と、最短で1本作る方法- frontmatter 仕様は「知っておくと良い」程度の補足扱い
- 作った後の運用で本当に効く 4 つの勘所 — description 設計、スキル競合、肥大化、スコープ設計
表記について：正式は SKILL.md（大文字）
細かい話から先に片付けておきます。検索流入を意識してタイトルと description には skill.md を使っていますが、ファイル名の正式表記は SKILL.md（すべて大文字）です。Anthropic 公式ドキュメントも大文字を採用していて、小文字の skill.md だとスキルとして認識されません。
macOS など大文字小文字を区別しないファイルシステムで作業していると、小文字でも動いているように見えます。ところが GitHub に push した瞬間、別ファイル扱いになる。CI で find を叩いたらスキルが認識されない、というしょうもない事故を過去に1度やりました。動いてるように見えるのが一番たち悪い。以降、この記事では SKILL.md で統一します。
一番簡単な作り方：Claude に頼む
結論から書きます。Skill の作り方で一番失敗しない方法は、これです。
- やりたい作業を一度、Claude Code と会話しながら手で通す
- 通し終わったあとに、こう頼む — 「今やった手順を skill 化して」
- 生成された
SKILL.mdを読み、足りない制約だけ追記する
たとえば最近作った blog-fact-check スキルは、最初は「この記事の統計値、公式ソースと合ってる？」と何度か依頼していただけでした。3 回くらい同じ依頼をしたあとに「これ毎回やる作業だから skill 化して」と頼んだら、Claude が自分で SKILL.md の雛形を提案してきて、その日のうちに動き始めました。仕様書は1行も読んでいません。
実際に使うプロンプト例
頼み方は、このくらい具体的でちょうどいいです。
今のやり取りで実施した「MDX 記事の統計値を抽出して公式ソースと照合する手順」を
Claude Code の Skill にしてほしい。
要件:
- スキル名は blog-fact-check
- 対象は content/blog/*.mdx
- 起動条件: ユーザーが「ファクトチェック」「事実確認」と言ったとき
- 副作用のあるコマンドは実行しない（読み取りのみ）
プロジェクト固有で使いたいので <project>/.claude/skills/ 配下に配置して。
Skills は 2026-04 現在、Claude Code の標準機能です。外部プラグインを入れる必要はありません。Claude Code は SKILL.md のフォーマットを知っているので、会話の中で「skill 化して」と頼めば frontmatter 付きの SKILL.md を書いてくれます。要するに 「自然言語で要件を渡す → Claude が SKILL.md を書く」 という順序にしてしまえば、ユーザー側が frontmatter の細かい仕様を暗記する意味は、ほぼありません。
生成された SKILL.md を読んでみる
Claude が吐き出す SKILL.md は、だいたいこんな形をしています。これが最小テンプレートでもあります。
---
name: blog-fact-check
description: 'MDX 記事内の統計データ・バージョン情報・料金を抽出し、公式ソースと照合する。ユーザーが「ファクトチェック」「事実確認」「この数字合ってる？」と言ったときに使う。'
---
# Blog Fact Check
MDX 記事の事実関係を検証するスキル。
## 実行手順
1. 対象ファイルから数値・固有名詞・バージョン番号を抽出する
2. それぞれについて公式ドキュメント・一次ソースを探す
3. 不一致があれば以下のフォーマットで報告する
```text
- <該当箇所>: 記事の値 <X> / 公式値 <Y> / ソース <URL>
```
## 注意事項
- 書き込み系のコマンドは実行しない
- ソースが見つからない場合は「要確認」として残す
ここで注目してほしいのは、frontmatter が name と description の2つしかないことです。これで正しい。入門段階ではこの2つで十分動きます。
allowed-tools / model / when_to_use / context といったオプションフィールドは確かに存在しますが、最初から全部盛る必要はありません。運用していて「ここで副作用を抑えたい」「このモデルを指定したい」となった瞬間に、該当フィールドを1つずつ足していけばいい。仕様書を暗記するより、必要になった瞬間に調べるほうが圧倒的に速いです。
ファイルの配置場所だけは、最初に決めておきます。個人用で全プロジェクト共通なら ~/.claude/skills/<name>/SKILL.md、プロジェクト固有でチーム共有したいなら <project>/.claude/skills/<name>/SKILL.md。この使い分けは後ろのセクションで触れます。
作った後に気をつけること（本題）
ここからが本題です。Skill は「作る」より「運用する」ほうが、正直なところ難しい。95 個を回してみた結果、初心者がハマるポイントはだいたい以下の4つに集約されました。
1. description の書き方で起動精度が決まる
Skill が意図通りに発火しない原因、その大半は description の書き方です。
Claude Code はセッション起動時、全 SKILL.md の description だけを読み込んで一覧をメモリに載せ、ユーザー発話と意味的に近いものを選びます。つまり description は「このスキルを呼ぶべき状況」を自然文で表した検索クエリとして書く必要がある。
悪い例と良い例を並べるとこうなります。
# Bad: 機能説明しかなく、いつ呼べばいいか書いていない
description: 'Fact check skill for MDX articles'
# Good: 動詞 + 対象 + 起動キーワードが揃っている
description: 'MDX 記事内の統計データ・バージョン情報・料金を抽出し、公式ソースと照合する。ユーザーが「ファクトチェック」「事実確認」「この数字合ってる？」と言ったときに使う。'
実運用でやらかした例を正直に書きます。blog-seo-improve の description を、最初は "Improve SEO of blog articles" とだけ書いていました。最初はこれで十分だと思っていました。違いました。「SEO 改善」と頼んでも全然起動しない。description を「GSC/GA データに基づいて title/description/冒頭セクションを改善する。ユーザーが『SEO 改善』『CTR 改善』と依頼したとき」に書き換えた瞬間、ピタッと呼ばれるようになりました。
description を書くときのチェックリストは、3つでいいです。
- 動詞で始める（
抽出して、分析する、変換する） - 対象オブジェクトを明示する（
MDX 記事、GitHub issue） - ユーザーがどう頼むかを自然文で書く（
〜と言ったとき/〜を依頼されたとき）
2. スキル同士の競合と優先順位
スキルが 10 個を超えたあたりから、「別のスキルが呼ばれる」現象が増えてきます。
うちで起きた事故はこんな感じでした。blog-mv-date（1記事の公開日移動）と blog-swap-dates（2記事の日付交換）が競合して、「A と B の日付入れ替えて」と頼んだのに blog-mv-date が発火してしまう。これ、ほんとに動くの？ と画面を二度見した瞬間です。
対策は、description 側で守備範囲を明示すること、これに尽きます。blog-mv-date には「単一記事の日付変更。2記事の交換には使わない」と書き、blog-swap-dates には「2記事間の日付交換専用」と書きました。スキル内部ではなく、選ばれる段階で差別化する必要があります。否定条件（〜には使わない）を書き添えるのは、競合が顕在化してからで十分です。
もうひとつ大事なのは、発火してほしくない場面を設計で潰すことです。粒度の似たスキルが並んでいる時点で、どれかは要らないか、あるいは1段上のオーケストレーター側で呼び分けさせるべき。私たちの dev-flow が dev-kickoff / dev-integrate / pr-iterate を呼び分けているのはこの考え方に基づいています。詳しくは Skills 設計パターン上級編 で触れています。
3. 肥大化したら references/ に分割する
最初は 50 行で済んでいた SKILL.md が、運用していくうちに 300 行を超えてきます。追加要件、例外処理、テンプレート、エラー対応、どれも書かないと挙動がブレるから削れない。気がつくと「SKILL.md の一覧ロードだけでコンテキストをごっそり食う」状態になっています。
ここで効くのが references/ への分割です。ワークフロー制御に関わる部分だけ SKILL.md に残し、テンプレート・詳細仕様・エラーパターン集は references/*.md に追い出す。Claude は必要になったときだけ references/ を読むので、普段のコンテキスト消費が激減します。
my-skill/
├── SKILL.md # 80 行（ワークフロー骨格のみ）
└── references/
├── templates.md # 出力テンプレート集
├── error-patterns.md # 既知の失敗と対処
└── examples.md # 過去の実行例
SKILL.md が肥大化してきたと感じたら、まず「これは毎回読ませる必要があるか？」を問うところから始めてみてください。起動判定と骨格だけ SKILL.md に残し、テンプレート・既知の失敗・過去の実行例は references/ に退避させる。常駐コンテキストから外すだけで、スキルの反応速度と精度が体感レベルで変わります。
4. プロジェクト固有 vs グローバルの線引き
「このスキル、どこに置く？」問題は毎回悩みますが、判断軸は1つだけです。
~/.claude/skills/<name>/— 入力値が環境によらないもの（例: git 操作、ファイル形式変換）<project>/.claude/skills/<name>/— プロジェクト固有の値を含むもの（例: GA4 プロパティ ID、出力先ディレクトリ、サイト URL）
プロジェクト固有値をグローバルスキルに書き込んだ瞬間、そのスキルは他プロジェクトで使えなくなります。逆にグローバルスキルに skill-config.json を読むロジックを持たせれば、プロジェクトごとに値を差し替えられる。このポータブル設計については Skills をポータブル資産にする に実装ごと書きました。
迷ったら、まずグローバルに置いてみて、プロジェクト固有値が出てきた時点で skill-config.json に外出しする順序が安全です。最初からプロジェクト配下に閉じ込めると、あとで「これ他プロジェクトでも使いたい」となったときの移植コストが無駄に高くつきます。
Skill の調整方法：SKILL.md を直接触るのは最終手段
運用していると、必ず「このスキル、思った通りに動かない」という場面が出てきます。このとき、いきなり SKILL.md をエディタで開いて手で直すのは、あまりおすすめしません。私たちの経験上、直接編集は最終手段です。
まずやるべきは、自然言語で Claude Code に相談することです。
blog-fact-check スキルを呼んだのに全然起動しない。
今「この記事の数字、公式ソースと合ってる？」って聞いたら別のスキルが動いた。
skill 側に問題ありそう？ description とか手順で怪しいところ見て。
これくらい雑に投げて構いません。Claude は該当の SKILL.md を読み、description の起動ワードが不足しているのか、競合スキルの守備範囲が広すぎるのか、手順の記述に曖昧さがあるのか、を特定してくれることが多いです。人間が仕様書を読み解くより速い。
ただし「メモリ保存で済ませる」罠に注意
ここで一番ハマりやすい落とし穴があります。Claude に「なぜ起動しなかったか」を相談すると、こんな返事が来ることがあるんです。
原因を確認しました。今後「この数字、公式ソースと合ってる？」と
言われたときは blog-fact-check を呼ぶように、
プロジェクトメモリに保存しておきました。
一見、気が利いていて親切に見えます。でもこれ、根本解決になっていないことが多いんです。メモリに「こう言われたらこのスキルを呼ぶ」と書き足すのは、完全に対症療法。本当に直すべきは SKILL.md の description や手順そのものです。メモリは個別プロジェクトに閉じるし、セッションをまたぐと効きが弱まるし、他のメンバーには共有されない。スキル本体が適切に書かれていれば、メモリに救済ルールを足さなくても起動するはずなんです。
そこで私たちは、Claude がメモリ保存で逃げてきたら必ずこう返すようにしています。
ちょっと待って。それメモリ保存で根本解決になってる？
スキル自体の description が「この数字合ってる？」みたいな
自然な問いかけをカバーしていないのが原因じゃないの？
SKILL.md 側を直す案も出して、比較させて。
この一言で、Claude は SKILL.md の description に起動ワードを追記する案を具体的に出してきます。そこで初めて「あ、やっぱりスキル本体の問題でしたね」と合意が取れて、diff ベースで修正が入る。メモリ保存は一見「学習させた感」があって気持ちいいんですが、スキル設計のバグを覆い隠してしまう。気づかずに放置すると、同じ話題でまた別のスキルが誤爆します。
調整時の順序まとめ
実務では、次の順序で触るのが安全でした。
- まず自然言語で「なぜ動かない / なぜ誤爆する」を Claude に聞く
- Claude が原因を特定したら、メモリ保存で逃げていないかを疑う
- 逃げていたら「スキル本体（description / 手順）の修正案も出して」と突っ込む
- 修正案の diff を確認し、納得できたら適用させる
- どうしても会話で詰められないときだけ、最終手段として SKILL.md を手で開く
SKILL.md を直接読みに行くのは、本当に最後でいいです。先に Claude との会話で論点を絞り込んだほうが、結局は短時間で終わります。
最短で1本動かすまでの具体手順
ここまでの話を踏まえて、初心者の方が今日1本動かすなら、この手順が最短です。
- やりたい作業を Claude Code と会話しながら1回通す
- 「今やった手順を
<name>という skill 名で skill 化して。プロジェクト固有だから<project>/.claude/skills/に置いて」と頼む - 生成された SKILL.md の
descriptionだけ読み返し、起動ワードが自然文で書かれているか確認する - Claude Code を再起動し、自然文で「〜して」と呼び出してみる
- 呼ばれなかったら description の起動ワードを足す、呼ばれすぎたら否定条件を足す
これで十分動きます。frontmatter の全フィールドを最初から理解している必要はありません。必要になったら追加する、で間に合います。
まとめ
SKILL.md（正式表記は大文字）は frontmatter + Markdown 本文の1ファイルで完結する- 書き方の最短ルートは「Claude Code に skill 化してと頼む」こと。仕様書を熟読する必要はない
- frontmatter は
nameとdescriptionの2つで、十分スタートできる - 運用で本当に効くのは、description の精度・スキル同士の競合管理・肥大化対策・スコープ設計の4点
- プロジェクト固有値は
skill-config.jsonに外出しして、スキル本体はポータブルに保つ - 調整は自然言語で Claude に相談するところから。ただし「メモリ保存で解決しました」で逃げさせない
Skill 化は「書き捨てていたプロンプトを資産に変える」最短経路です。最初の1本を完璧に書こうとしないでください。雑に作って、運用しながら description を研ぐ。結果として、これが一番早く良いスキルになります。
