AIがルールを守らないのはCLAUDE.mdの書きすぎかもしれない —— 必要なときだけ読む「スキル」の仕組みと使い方

AIが言うことを聞かない

1,200行に膨らんだCLAUDE.md（イメージ）

# 和菓子ECショップ
- お店の名前・使う道具・フォルダの場所
## 商品ページの作り方 ……… 320行
## お知らせメールの書き方 … 280行
## 材料の発注の手順 ……… 240行
## 売上のまとめ方 ………… 200行
## そのほかの決まり ……… 150行

お店の商品ページ、お知らせメール、材料の発注、売上のまとめをAIエージェントに手伝ってもらうため、すべての作り方をCLAUDE.mdに書いたとします。CLAUDE.mdは、AIが作業のたびに最初に読むメモです。[s2]作業を増やすたびに書き足し、1,200行になりました（イメージ）。

よくある困りごと

ところが、新作のページを頼むとお店の色を使わないどこかで見たようなページになり、メールの決まりの一文も忘れます。書き足すほど、以前は守れていたことまで守れなくなっていきます。原因は、書きすぎにあります。作業の手順は、必要なときだけ開く手順書に分けるべきなのです。この手順書が「スキル」です。[s1][s4]

書きすぎると、なぜ守られないのか

AIの机（コンテキスト）のイメージ

AIには、一度に見られる量に限りがあります。ここでは、それを「机」と呼びます。CLAUDE.mdは、作業を始めるたびに、まるごとこの机に載ります。[s2]メールの誤字を1つ直してほしいだけのときでも同じで、机の大部分が、いまの作業と関係のない手順で埋まってしまいます。

CLAUDE.mdの長さの目安

Claude Codeの公式の説明では、1つのCLAUDE.mdは200行未満が目安です。長いファイルほど机を多く使い、指示が守られにくくなると書かれています。[s2]Anthropicのブログも、デザインの指示をいつもの指示に全部入れると、プログラムを直すときも、データを分析するときも、メールを書くときも、デザインの指示がずっとついて回ると説明しています。[s7]

新人の初日、どちらが覚えやすいか

人に置き換えると分かりやすくなります。新しいアルバイトの初日に、1,200ページのマニュアルを渡して「全部覚えて」と言うか、1枚の「お店の基本」と、作業ごとに開く引き出しを渡すか。Anthropicも、スキル作りを新人への手引き作りにたとえています。[s4]

スキルの仕組み —— 3段階で読む

スキルのフォルダ（イメージ）

.claude/skills/
├─ shop-mail/ お知らせメール
├─ order/ 材料の発注
└─ shop-page/ 商品ページ ├─ SKILL.md 手順書（必ず1つ） ├─ references/ くわしい資料 └─ scripts/ 確かめるプログラム

スキルは、作業ごとの手順書をフォルダにまとめたものです。[s4][s5]お店なら、商品ページ用、メール用、発注用と、1つの作業に1つのフォルダを作ります。中心になるのがSKILL.mdという手順書で、くわしい資料や確かめるプログラムも一緒に入れられます。[s4][s5]

SKILL.mdの中身（イメージ）

---
name: shop-page
description: 商品ページを作る・直すときに使う。 メールや発注には使わない。
---
# 商品ページを作る
1. references/brand.md で色と文字を確かめる
2. 値段とアレルギーの表示を必ず入れる
3. scripts/check.sh でスマホの幅を確かめる
4. 画面を撮り、決まりと見くらべてから完成と言う

SKILL.mdのいちばん上には名前と説明を書き、その下に手順を書きます。[s5]この例では、名前は「shop-page」で、説明には何をするかと、いつ使うかを書いています。[s6]手順は、お店の色を確かめ、必要な表示を入れ、最後に画面で見比べる、という流れです。

スキルの読み方は3段階

大事なのはAIの読み方で、3段階に分かれています。最初に机に載るのは、名前と説明の短い「名札」だけで、1つあたり約100トークンです。使うと決めたら手順書を開き（500行未満が目安）、くわしい資料やプログラムは必要になったときだけ使います。[s1][s5]

スキルに分けたあとの机

先ほどの机と比べると、いつも載っているのは、短くしたCLAUDE.mdとスキルの名札だけです。[s1]「秋の新作のページを作って」と頼むと、AIは名札を見て商品ページの手順書だけを開き、手順書に「お店の色の資料を見て」とあれば、その資料も開きます。[s1][s4]メールの誤字を直すときは、ページの手順書は開かないため、机は軽いままです。

スキルの呼び出し方

# Claude Code
/shop-page 秋の新作「抹茶モンブラン」 # Codex
$shop-page 秋の新作「抹茶モンブラン」

スキルの呼び出し方は2つあります。AIが説明を見て自分で開く方法と、人が名前で呼ぶ方法です。名前で呼ぶときは、Claude Codeでは「/」、Codexでは「$」に続けてスキルの名前を書きます。[s1][s11]公開や送信のように、勝手に実行されると困るスキルは、人が呼んだときだけ使うように設定することもできます。[s1]

スキルに分けたあと（イメージ）

スキルに分けたあとは、AIが商品ページの手順書と色の資料を読み、スマホの幅で画面を確かめてから「完成」と答えるようになります（イメージ）。

説明文がいちばん大事

スキルでいちばん大事なのが、名札に書く説明文です。AIは名札の説明文を見て、どの手順書を開くかを決めるからです。[s1][s6]「お店のことなら何でも使う」のような説明では、メールの誤字を直すときにも商品ページの手順書を開いてしまいます。何をするかに加え、いつ使い、いつ使わないかをはっきり書くのがコツです。[s6][s11]

OpenAIも9月のガイドで同じ注意をしています。悪い例は「データベース・クエリ・モデルを扱うときに使う」で、これではデータベースに触れるたびに読み込まれてしまいます。良い例は「マイグレーションを追加・変更するとき、その展開を見直すときに使う」です。[s13]

名札の一覧に使える量

名札を置ける場所にも限りがあります。Claude Codeでは机の1%まで、Codexでは2%までです。[s1][s11]スキルを入れすぎると説明が削られ、AIがどれを開くべきか迷いやすくなります。[s1][s13]

実際のスキル① frontend-design

ここからは、実際に人気のスキルを2つ紹介します。1つ目は、Anthropicが公開している「frontend-design」で、SKILL.mdが1枚だけのシンプルなスキルです。スキルの一覧サイトでのインストール数は約96万回ですが、これは人気の目安です。[s9][s15]

AIが選びやすいデザイン（イメージ）

もともとの悩みは、AIに画面を頼むと、どれも似た見た目になることでした。2025年のブログでは、白い背景に紫のグラデーション、文字はInterという例が挙げられています。AIは、学んだたくさんのページの中から、いちばん無難な真ん中を選びやすいのです。[s7]

frontend-designの中身（要約）

このスキルは「デザイン会社のリーダーのつもりで」という書き出しで始まります。何のお店か、誰向けかといった題材から考えること、先に色と文字の計画を作って「いつもの見た目」になっていないかを見直すこと、派手さは1か所だけにしてほかは静かにまとめることを指示しています。[s9]「出かける前に鏡を見て、アクセサリーを1つ外す」というシャネルの言葉も引かれています。[s9]

「避ける見た目」の移り変わり

いまの版は、AIが作りがちな見た目を5つ名指しで挙げています。この部分は書き直されてきており、2025年の版では「紫のグラデーションやInterを使わない」でしたが、2026年6月にはクリーム色の背景にれんが色の差し色など3つの見た目に変わり、9月に5つに増えました。[s7][s9]AIが作りがちな見た目自体も、時期によって変わっていくのです。

実際のスキル② ui-ux-pro-max

入っているデータ（2026年10月時点）

2つ目は、コミュニティで人気の「ui-ux-pro-max」です。考え方だけでなく、調べられるデザインのデータが入っているのが特徴で、見た目のスタイルが79種、配色が192通り、文字の組み合わせが74、使いやすさの決まりが119含まれています。[s10]

検索のプログラム

$ python3 scripts/search.py "beauty spa" --design-system
ページの型：大きな画像＋お客さんの声
スタイル　：やわらかい立体（Soft UI）
配色 ：やさしいピンク・セージ・金
文字 ：Cormorant Garamond ＋ Montserrat
避けること：AIっぽい紫やピンクのグラデーション

データを活かすために、検索のプログラムが付いています。公式の説明の例では、エステのお店と入れると、合うページの型・スタイル・色・文字をまとめて出し、避けることの欄には「AIっぽい紫のグラデーション」が挙がります。[s10]データの表は机に載せず、プログラムが合う行だけを探すため、軽く使えます。[s10]

納品前のチェック（一部）

納品前のチェックもあり、文字と背景の明るさの差（4.5:1以上）、指で押せる大きさ（44px以上）、アイコンに絵文字を使わないこと、などが並んでいます。[s10]題材に合った個性を出したいときはfrontend-design、決まった型で抜けなく作りたいときはui-ux-pro-max、と使い分けられます。

CLAUDE.md・スキル・MCP・フックの使い分け

どこに書くか（お店の例）

スキルを使えばCLAUDE.mdが不要になるわけではありません。役目が違います。お店の名前や使う道具のように、いつも知っておくことはCLAUDE.mdに、ページの作り方のような作業の手順はスキルに書きます。在庫の表のような外部のデータを見るならMCP、公開の前に毎回必ず確かめたいことはフックです。[s3][s8]

スキルとフックの違い

毎回必ず確かめたいことをフックにするのは、スキルがあくまでAIが読んで判断する手順書だからです。公式の説明にも、毎回必ず守らせたいルールはフックに移すよう書かれています。[s1]

Claude CodeとCodex

Codexでも考え方はほとんど同じで、いつも読むメモがAGENTS.mdであることや、スキルの置き場所と呼び出す記号が少し違う程度です。[s1][s11]SKILL.mdの形は「Agent Skills」という共通の決まりで、Anthropicが作り、2025年12月に誰でも使える標準として公開しました。公式サイトの一覧には46の製品が並んでいます。[s4][s5][s16]

OpenAIの使い方

AGENTS.mdにはスキルを使う決まりだけを書く

## スキルを使う決まり
- コードを変えたら → $code-change-verification
- 仕上がったら → $pr-draft-summary

OpenAIは、自社の開発でのスキルの使い方を公開しています。確かめる作業、説明書をコードにそろえる作業、公開前の見直しといった、くり返す仕事をスキルにし、AGENTS.mdには「コードを変えたら、確かめるスキルを使う」のような短い決まりだけを書いています。[s12]

OpenAIは、3か月で取り込んだ変更（PR）の数が316件から457件に増えたと発表しています。ただし、これは会社の発表で、ほかの変化も含まれるため、スキルだけの効果とは言えません。[s12]コツとして挙げられているのは、1つのスキルに、狭い役目とはっきりした合図、具体的な成果物を持たせることです。[s12]

注意点 —— 中身を読んでから入れる

公開されたスキルの調査

注意点は3つあります。1つ目は、他人のスキルは中身を読んでから入れることです。スキルにはプログラムも入れられるため、悪意のあるスキルなら、パスワードなどを外部に送らせることもできます。[s4]セキュリティの会社Snykが公開されたスキル3,984個を調べたところ、13.4%（およそ7〜8個に1つ）に重大な問題が見つかり、76個は人が確かめて悪意があると判断されました。[s14]

インストール数は人気の目安であって、安全の保証ではありません。Anthropicも、信頼できるところからだけ入れ、そうでなければ入れる前に中身を読むよう勧めています。[s4]

2つ目は、必ず守らせたいことは、スキルではなくフックやCIで守らせることです。[s1]3つ目は書きすぎないことで、AIがすでに知っていることは書かなくて構いません。[s6]OpenAIも、賢いモデルには細かすぎる手順がかえって邪魔になることがあると書いています。[s13]SKILL.mdは500行未満を目安にし、くわしい話は別のファイルに分けましょう。[s1][s5]

今日からできる4つのこと

スキルを作る4つの手順

同じ説明を3回チャットに貼ったら、それはスキルにする合図です。[s3]次に、CLAUDE.mdの中で手順になっている部分を切り出し、CLAUDE.mdにはいつも知っておくことだけを残します。[s1][s2]スキルの説明文には、いつ使うか、いつ使わないかを短くはっきり書きます。[s6]最後に、スキルがあるときとないときで同じ頼みごとを比べ、効果を確かめます。比べるときは、スキルを作るためのスキル「skill-creator」が便利です。[s1][s11]

まとめ

CLAUDE.mdは短くし、いつも知っておくべきことだけを書きましょう。[s2]作業の手順はスキルに分け、説明文で、いつ使うかをはっきりさせます。[s1][s6]

必ず守らせたいことはフックで守らせ、他人のスキルは中身を読んでから入れるようにしましょう。[s1][s4]AIがルールを守らないときは、大きな字で書き足す前に、書きすぎていないかを見直すことが近道です。