SKILL.md の書き方：項目、フォルダ、文字数の上限

項目

Agent Skills の仕様、Claude Docs、Claude ヘルプセンター（2026 年 11 月 5 日に確認）にもとづきます。

フォルダと読み込み方

1. メタデータ、いつも：入れてあるすべてのスキルの name と description。1 つおよそ 100 トークン。
2. 指示、作業が合ったとき：SKILL.md の本文。500 行未満に。
3. 資料、必要なときだけ：scripts/、references/、assets/ のファイル。SKILL.md から相対パスで、1 階層までで参照する。

例

架空の例です。ある制作会社の週次の顧客レポートを、weekly-client-report というフォルダの完全なスキルにしたもの。ひな形は assets/ に置いています。

---
name: weekly-client-report
description: 担当者のメモから週次の顧客レポートを書く。状況、目標に対する結果、顧客にしてほしいこと、来週。週次レポートや顧客への進捗の連絡を頼まれたときに使う。
metadata:
  owner: account-leads
  version: "1.2"
---
# 週次の顧客レポート

1. 最初に状況を 1 行で：予定どおり、遅れの恐れ、遅れ、とその理由。
2. メモにある目標に対する結果。メモにある数字だけを使う。
3. 今週したこと：3 つまで。
4. 顧客にしてほしいこと、期日つきで。なければそう書く。
5. 来週：3 つまで。

assets/report-template.md のひな形を使う。
答える前に確かめる：どの数字もメモから。顧客への依頼に期日がある。

name はフォルダと同じで、description は何をしいつ使うかをみんなが打つ言葉で書き、claude.ai 用に 200 文字に収めています。ひな形は、スキルが動くときだけ読み込まれるファイルに置いています。

自分のスキルを確かめる

1. name がフォルダと同じで、小文字とハイフンか。
2. description が何をし「〜のときに使う」を、チームの言葉で書いているか。
3. 本文が手順とルールで、AI がすでに知っている説明ではないか。
4. 長い資料を references/ に移し、SKILL.md から参照しているか。
5. 仕様の skills-ref で検証し、新しいチャットで試す。

次の一歩：ファイルを 1 回で共有する

ZIP で回したフォルダは、写しに分かれていきます。1 つの版を保つ方法はAI のプロンプトを小さなチームで安く共有する方法で比べています。description には別の手間をかける価値があります。スキルの説明文の書き方で。チームのやり方が Gemini の Gem にあるなら、Google は 11 月 17 日からそれをこの形式のスキルに移します。手順はGemini の Gem は 11 月 17 日に使えなくなる：スキルへの移し方で。

よくある質問

SKILL.md とは？

フォルダをスキルにするファイルです。冒頭の YAML に少なくとも name と description を書き、そのあとに指示を Markdown で書きます。フォルダには、指示が参照するスクリプト、参考資料、素材も置けます。

SKILL.md の項目の上限は？

Agent Skills の仕様では、name は 1〜64 文字の小文字・数字・ハイフンでフォルダ名と同じ、description は 1〜1,024 文字です。Claude のドキュメントは、どちらにも XML タグを入れず、name に「anthropic」「claude」を含めないことを加えています。claude.ai にアップロードするスキルの description は、Claude ヘルプセンターでは 200 文字までです。

SKILL.md は Claude 以外でも使える？

使えます。形式は agentskills.io で公開されたオープンな標準で、ほかのツールも読みます。たとえば Gemini は、SKILL.md をアップロードして、ほかのプラットフォームで作ったスキルを取り込めます。