SKILL.md の書き方｜収録 470 件を実測して分かった型

まず結論

必須の項目（name と description）

2 つ

description の長さの中央値

373 文字

2 つの必須項目を持っていたスキル（470 件中、2026-09-19 時点）

469 件

allowed-tools を使っているスキル（2026-09-18 時点）

約 14%

スキルはフォルダです

中心に SKILL.md を置き、必要なら参照資料とスクリプトを同じフォルダに入れます。

your-skill/
├── SKILL.md        ← 名前・説明・手順
├── references/     ← 参照資料（任意）
└── scripts/        ← スクリプト（任意）

必須の項目は 2 つだけ

SKILL.md の先頭には frontmatter（--- で囲んだ YAML）を書きます。共通の仕様（Agent Skills の仕様）で必須なのは 2 つだけです。

仕様上の任意項目は license allowed-tools metadata compatibility。仕様の検証ツール（skills-ref）は、これ以外の項目をエラーにします。

一方で Claude Code は、知らない項目をエラーなしで無視します（公式ドキュメント、2026-10-09 確認）。つまり勝手な項目を足しても動きますが、何も起きません。Claude Code では name も任意で、省くとフォルダ名が使われます。

name の制約

仕様が決めている 5 つの制約

仕様は name に次の制約を置いています（2026-10-09 確認）。

• 使えるのは小文字・数字・ハイフンだけ
• 上限 64 文字
• ハイフンで始めたり終わったりしてはいけない
• ハイフンを 2 つ続けてはいけない（pdf--processing は不可）
• フォルダ名と一致していること

外したときの扱いは実行環境ごとに違う

my-skill/ の中の SKILL.md に name: my_skill や name: My Skill と書くと、仕様違反です。検証ツールの skills-ref validate で落ちます。

ただし、実行環境が読み込みを拒むとは限りません。仕様の側が実装者向けに出している手引きは、フォルダ名との不一致や 64 文字超は警告して読み込むことを勧めています。

Claude Code では、name は / で呼ぶときの名前になり、フォルダ名でも呼べます。フォルダ名と違っていても読み込まれます（公式ドキュメント、2026-10-09 確認）。

実データでは事実上、必ず書かれている

当サイトは、収録するスキルを frontmatter の name で突き合わせています。実データで 470 件中 1 件だけ frontmatter がありませんでした（2026-09-19 時点）。

残り 469 件はすべて name と description を持っていました。この 2 つは事実上、必ず書かれています。

description の書き方

実測: どれくらいの長さで書かれているか

当サイトが収録している 470 件の SKILL.md を実際に測りました。2026年9月19日時点で、frontmatter が無い 1 件を除いた 469 件の集計です。

最短

18 文字

中央値

373 文字

平均（合計 192,396 文字 ÷ 469 件）

410 文字

最長

1,068 文字

仕様上の上限は 1,024 文字です。当サイトの計測では 3 件がこれを超えていました（claude-api 1,068 / ai-music 1,048 が 2 件）

「1 行で簡潔に」とは書かれていない

中央値が 373 文字というのは、多くの人の想像より長いはずです。「1 行で簡潔に」と書かれた解説をよく見ますが、実際に流通しているスキルはそうなっていません。

長く書かれている理由

Anthropic 公式のスキルを見ると意図が分かります。

中身は発動する条件の列挙です。xlsx の説明は「表計算ファイルが主な入力または出力になる作業すべて」から始まり、.xlsx .xlsm .xltx .csv .tsv を名指しします。

さらに使ってはいけない場面（成果物が Word 文書や HTML レポートの場合）まで書いています。

書き方の指針

「何をするか」と「いつ使うか」を両方書く。仕様が要求しているのはこれです。

description: PDF の読み取り（本文・表）、結合、分割、回転、フォーム入力、
  スキャン PDF の OCR を扱う。PDF が入力または成果物になる作業で使う。
  Word や Excel のファイルには使わない（docx / xlsx を使う）。

効かせるための具体策は 3 つ

1. 利用者が実際に打つ言葉を入れる「請求書」「見積書」「議事録」のような具体的な語のほうが当たります。抽象語だけでは呼ばれません
2. 使わない場面を書く似たスキルを複数入れたときに、どれが呼ばれるかが安定します
3. 扱う拡張子や固有名詞を並べる.xlsx Firestore azd のような語は判定の手がかりとしてよく効きます

避けるのは、対象が広すぎる説明

「コードを良くします」「文章を改善します」では、いつ呼ぶべきかが決まりません。

実際に使われている項目

470 件の frontmatter を集計した

左が項目名、右が使っている件数です（2026-09-18 時点）。

注意すべきは「仕様外」の行

version を最上位に書いているものが 51 件ありますが、仕様にない項目なので、Claude Code は黙って無視し、検証ツールはエラーにします。

一方 metadata の中に version を入れているものは 136 件。同じ情報を、無視される場所に書いている例が 51 件あるということです。

metadata の中でよく使われているもの

allowed-tools は「絞る」項目ではない

470 件中 64 件（約 14%、2026-09-18 時点）が allowed-tools を使っています。仕様では「事前に承認する道具」の一覧で、実験的な項目です。

Claude Code では確認なしで使える道具の一覧

Claude Code では、ここに並べた道具を、そのスキルを呼んだ回だけ確認なしで使えます。ほかの道具が使えなくなるわけではありません。並べていない道具は、利用者の権限設定のとおりに確認が出ます（公式ドキュメント、2026-10-09 確認）。

道具を使えなくするのは別の項目 disallowed-tools（Claude Code の拡張）です。

自分の CLI を確認なしで走らせる例

allowed-tools: Bash(agent-browser:*), Bash(npx agent-browser:*)

これは agent-browser の実例です。自分の CLI だけを確認なしで走らせる指定です。ほかのシェルコマンドを禁じるものではありません。

取得を確認なしで許す例

allowed-tools: WebFetch

こちらは Clerk のスキル（17 件がこの 1 行、2026-10-09 確認）。ドキュメントを読むので、取得を確認なしで使えるようにしています。

配布するスキルでは最小限にする

使う側から見ると、allowed-tools は確認を飛ばして使われる道具の一覧です。「このスキルは何を確認なしで実行しうるのか」が frontmatter だけで分かります。

配るスキルでは、本当に毎回使う道具だけに絞って書いてください。Bash をそのまま並べると、シェルの実行が確認なしで通ります。

本文の書き方

スキルであるもの／ないもの

obra/superpowers の writing-skills がはっきり定義しています。

自作のスキルが効かないとき、たいてい後者になっています。「先週この不具合をこう直した」は記録であってスキルではありません。

書いても行動が変わらないことを書かない

これが最もよくある失敗です。人はつい「エージェントが既にできていること」を丁寧に書きます。それは書いても何も変わりません。

writing-skills の言い方が鋭いので引きます。

スキル無しでエージェントが失敗するのを見ていないなら、そのスキルが正しいことを教えているかは分からない。

参照資料とスクリプトを分ける

本文が長くなるなら、references/ に切り出して本文から参照させます。

実データでは microsoft/azure-skills/azure-prepare が同梱ファイル 165 件を持っていて、Azure のサービスごとに参照資料を分けています。

同梱のスクリプトを置く場合、使う側はそれが実行されうることを知る必要があります。当サイトは各スキルのページで、同梱スクリプトの件数と言語を出しています。

検証する

試さないと分からない

書いたスキルが効いているかは、試さないと分かりません。 2 つの公開元がそれぞれの方法を出しています。

呼ばれないなら説明文だけを直す

skill-creator には説明文だけを最適化するスクリプトも別にあります。「作ったのに呼ばれない」症状なら、そこだけ使うのが最短です。

呼ばれない原因の切り分けはスキルが呼ばれないときの直し方に起きやすい順にまとめています。

よくある質問

description は日本語で書いてもいいですか

書けます。ただし判定に効く語は、利用者が実際に打つ言葉です。日本語で依頼するなら日本語の語を、英語で依頼するなら英語の語を入れてください。両方を並べて書いても問題ありません。

実データでは 470 件のほぼ全部が英語で書かれていますが、それは公開元が英語圏だからで、日本語が不利なわけではありません。

フォルダ名と name が違うとどうなりますか

仕様違反ですが、読み込まれるかは実行環境しだいです。 Claude Code は読み込み、name とフォルダ名のどちらでも / で呼べます。仕様の手引きも「警告して読み込む」を勧めています（2026-10-09 確認）。

「入れたのに出てこない」ときは、まず置き場所を確認してください（Claude Code は .claude/skills、Codex は .agents/skills。詳しくは導入ガイド）。

次に frontmatter が YAML として読めるかです。Claude Code は読めない frontmatter を空として扱うので、/名前 では動いても、説明文で呼ばれなくなります。

disable-model-invocation は何ですか

Claude Code の拡張項目で、true にすると自動で呼ばれなくなります。/名前 で手動で呼ぶ形になります。実データでは 23 件が使っています。意図せず発動してほしくない、影響の大きいスキルに向きます。

user-invocable はその逆で、false にすると手動のメニューから隠せます。項目を使っているのは 7 件ですが、false にしているのは 2 件だけで、残りの 5 件は true（既定と同じ）を明示しています。

1 つのスキルにどこまで詰めるべきですか

呼び出しの条件が 1 文で書ける範囲に収めるのが目安です。条件が「AかつB、ただしCのときは別」と分岐し始めたら、分けたほうが安定します。

実データでも、大きな公開元は 1 つの巨大なスキルではなく、azure-prepare / azure-validate / azure-deploy のように工程で分けたうえで互いを参照させています。

計測の方法を教えてください

当サイトが収録している 470 件の SKILL.md（GitHub から取得して保存したもの）の frontmatter を機械的に解析しました。項目の集計は 2026年9月18日時点、description の長さは 9月19日時点です。

最上位のキーは行頭がインデントされていない キー: の行を数え、description は YAML のブロック記法（> |）を展開してから文字数を数えています。ブロック記法の連結は行を空白でつなぐ方式なので、文字数は数文字の誤差を含みます。