SKILL.mdの書き方｜3段で決める、最初の1本を書き切る手順

「nameとdescriptionは埋めました。そのあと、何を書けばいいんでしょうか」。スキルを1本作ろうとした人から、この質問が出ます。

雛形そのものは公式ドキュメントに載っています。ところが、埋めたあとの本文をどこまで書くか、どこから別のファイルへ移すかは、雛形の外側にあります。手が止まるのはたいていここです。

この記事は、SKILL.mdを最初から最後まで1本書き切るまでを追います。素材は公式ドキュメントの記載と、新入社員の受け入れ準備を作るスキルを実際に組み立てた例です。

進行役は3人です。若葉さんが言葉のところから聞き、高梨課長が自分の手で書く側から聞き、鈴木さん（本誌監修）が答えます。

01SKILL.mdの書き方は、AIエージェントに何をさせる指示書なんですか？

若葉さん

若葉さんの発言

SKILL.mdって、結局のところ何を書くファイルなんでしょうか。

鈴木さん

鈴木さんの発言

引き継ぎのメモに近いと思っています。表紙に呼び名と「どんなときに開くか」を書いて、中身に手順を書く。細かい資料は別紙にして、要る人だけが開く。その形をファイルにそろえたものです。

SKILL.mdは、AIエージェントに定型の仕事を渡すための1枚です。書く内容は、次の3つの決定に分かれます。

• フロントマターで、nameとdescriptionを決める
• 本文を、概要・手順・例外の順で書く
• 行数が増えた部分を、references・scriptsへ切り出す

この順番には理由があります。次の章で見るとおり、3つは読み込まれるタイミングが違うためです。先に本文から書き始めると、どこまでを表紙に出すかが決まらないまま長くなります。

何をスキルにするかの線引きと、命名・分割の型そのものは、AIエージェントのスキル設計｜呼ばれる単位に分ける4つの型で扱っています。本記事は、その線引きが済んだあとの「1本を書き切る」ところだけを担当します。

例として、新入社員のオンボーディングチェックリストを作るonboarding-checklistというスキルを、nameを決めるところから組み立てます。

02SKILL.mdは、AIエージェントが読むタイミングで何が変わるんですか？

Claude Codeは、スキルの内容を3つの階層に分けて読み込みます。起動時に読むのは、nameとdescriptionだけです。本文は発火した瞬間に読み込まれます。参照ファイルとスクリプトは、本文が実際に呼んだ時だけ読み込まれます（出典: Anthropic公式Skills概要）。

（出典: Anthropic公式Skills概要）

この表で押さえるのは、内容の重要度ではありません。費用を払う時点です。呼び名と説明文は、使わない日も抱え続けます。本文は呼ばれた回だけ、参照ファイルは開いた回だけ払います。

だから、書く場所を選ぶ作業は「短くまとめる技術」ではありません。いつ払うかを選ぶ作業です。常に抱えるところへ長い文章を置けば、その重さは毎日ぶんになります。

3つの決定が、フロントマター→本文→切り出しの順で並ぶ理由もここにあります。いちばん高い場所から順に、何を残すかを決めていく並びです。

03SKILL.mdを置く場所は、AI導入のどの単位で決めるんですか？

高梨課長

高梨課長の発言

自分ひとりで使うのと、同じ現場の全員で使うのとで、置き場所は変えるものでしょうか。

鈴木さん

鈴木さんの発言

配布したい範囲で決めています。手元だけで試すなら個人用、同じプロジェクトを触る人全員に効かせたいならプロジェクト用です。最初の1本は個人用のほうが、取り消しが楽だと思います。

置き場所は、配布範囲で選びます。個人用は~/.claude/skills/、プロジェクト用は.claude/skills/です。本記事は、個人用フォルダに1本作る前提で進めます。

特別な権限は要りません。必要なのは、置き場所を決めることと、ファイルを書く権限だけです。書き始める前に確かめるのは、次の3点です。

• Claude Codeがインストール済みであること（バージョンはclaude --versionで確認する）
• 個人用かプロジェクト用かを決めていること（配布範囲で使い分ける）
• 同じ名前のスキルが無いことをlsで確認していること

mkdir -p ~/.claude/skills/onboarding-checklist

検証環境は、Claude Code公式ドキュメント（code.claude.com/docs）です。Anthropic公式ドキュメント（platform.claude.com/docs）もあわせて確認しています。いずれも2026-08-02時点の記載です。

04SKILL.mdのnameは、生成AIから見て何を名乗る欄なんですか？

nameは、そのスキルの呼び名です。制約は4つあります。

• 64文字以内であること
• 小文字・数字・ハイフンのみであること
• XMLタグを含まないこと
• 予約語（anthropic・claude）を含まないこと

（出典: Anthropic公式ベストプラクティス）

onboarding-checklistは20文字で、この4条件を満たします。命名の型を選ぶ基準はここでは扱いません。本記事が見るのは、制約を満たしているかの最終チェックだけです。

4つの制約は、どれも形の話です。判断が要るのは、次に決める説明文のほうです。

05descriptionの書き方は、AIエージェントが呼ばれる条件にどう効くんですか？

descriptionは、何をするか・いつ使うかの2部構成で、1,024文字以内に書きます（出典: Anthropic公式ベストプラクティス）。省略した場合、Claude Codeは本文冒頭の段落を代わりに使います（出典: Claude Code公式ドキュメント）。省略せず明示したほうが、発火条件は安定します。

---
name: onboarding-checklist
description: 新入社員の受け入れ準備を、部署・雇用形態別のテンプレートから生成する。新しく人が入ると聞いたとき、または初日から1か月のタスクを整理したいときに使う。
---

チェックの並びが示すのは、直していく順序です。形の誤りは見た瞬間に分かりますが、説明文の中身は、書き直しても効いているかどうかが目に見えません。だから先に形を片づけ、判断が要る欄だけを残します。

name・description以外のフィールドは、必要になった時だけ足します。

（出典: Claude Code公式ドキュメント）

argumentsを使うと、本文で$departmentのように名前で参照できます。

---
name: onboarding-checklist
description: 新入社員の受け入れ準備を、部署・雇用形態別のテンプレートから生成する。新しく人が入ると聞いたとき、または初日から1か月のタスクを整理したいときに使う。
argument-hint: [部署名] [雇用形態]
arguments: [department, employment_type]
---

呼ばれる条件そのものを詰めたいときは、Claude Codeのスキルが発火しない｜descriptionを直す4層にまとめています。

06SKILL.mdの本文の書き方は、AI社員にどこまで説明すればいいんですか？

若葉さん

若葉さんの発言

親切に書いたほうがいいと思って、つい説明を足してしまいます。

鈴木さん

鈴木さんの発言

そこは逆に働くことがあります。相手はもう知っているかもしれない。だから足す前に、この1文はうちの事情なのか、それとも一般的な話なのかを分けています。うちの事情だけが残る、という感覚です。

Anthropic公式は、Claudeを既に知識のあるモデルとして扱うことを勧めています。説明を足す前に、「Claudeは本当にこれを知らないか」を1文ずつ確かめます（出典: Anthropic公式ベストプラクティス）。onboarding-checklistの本文なら、テンプレートの選び方だけ書けば足ります。チェックリストとは何かを説明する必要はありません。

作業の自由度によって、書き方の粒度も変えます。

（出典: Anthropic公式ベストプラクティス）

2軸に置き直すと、表だけでは見えないものが出てきます。何も書かなくてよい区画です。相手が知っていて、しかも外れても直せる作業。ここに文章を足しても、発火のたびに費用だけがかかります。

削る判断は、書く判断より難しく感じます。ただ、削る対象は文章の出来ではありません。区画を見て、そこにあるべきでない文を外すだけの作業です。

07SKILL.mdの手順は、AIエージェントが読む順番でどう並べるんですか？

本文は、概要→手順→例外の3層で並べます。それぞれの役割は次のとおりです。

• 概要：1〜2文で、何をするスキルかを言い切る
• 手順：最も多いケースを先に示し、番号付きのステップを続ける
• 例外：まれなケースを短く書き、詳細は参照ファイルへリンクする

# オンボーディングチェックリスト作成

新入社員の受け入れ準備を、部署・雇用形態別のテンプレートから生成する。

## 手順

対象者の部署と雇用形態を確認し、templates/standard.mdの項目を埋める。

進捗:
- [ ] 手順1: 部署名と雇用形態を確認する
- [ ] 手順2: 入社日から初日・1週間・1か月のタスクへ逆算する
- [ ] 手順3: 部署固有の準備物をreferences/department-notes.mdで確認する

## 例外

雇用形態が業務委託のときは、社内SSOの発行手順が異なる。詳細は[CONTRACTOR.md](CONTRACTOR.md)を見る。

この並びが崩れる場面が1つだけあります。データを先に取得してから指示を出したい時です。` !command `という書き方で、Claudeが本文を読む前に、コマンドの実行結果へ置き換わります（出典: Claude Code公式ドキュメント）。この時だけ、データを先に置き、指示をあとに書きます。

例外がこの1つだけなのは、既定の並びが「読む側が上から必要な分だけ拾える」形になっているからです。材料を先に置く並びは、その拾い方を崩す代わりに、判断の材料をそろえてから読ませます。

08一度読まれたSKILL.mdは、AI活用のあいだずっと居座るんですか？

一度発火したSKILL.mdの内容は、そのままではセッション中ずっとコンテキストに残ります。ただし会話が長くなり自動要約が働くと、直近に呼んだスキルほど優先され、古い呼び出しほど丸ごと落ちることがあります（出典: Claude Code公式ドキュメント）。

層を分けて簡潔に保つ意味は、行数の見た目にはありません。この居座るコストと、要約されたときの生き残りやすさにあります。長い本文は、居座るあいだは重く、落ちるときは丸ごと落ちます。

丸ごと落ちるという性質は、分けておく理由をもう1つ足します。別紙へ出してあれば、必要になった時にもう一度たどり直せます。本文に書き切ってしまうと、落ちたあとに取り戻す道が残りません。

09SKILL.mdをreferencesとscriptsへ切り出す基準は、AI導入で何を守るんですか？

高梨課長

高梨課長の発言

どのくらい長くなったら、別のファイルへ分けるものでしょうか。

鈴木さん

鈴木さんの発言

行数も見ますが、先に中身の性質で決めています。読んで解釈してほしいものと、そのまま実行してほしいものは、置き場所を分ける。混ぜたまま伸ばすと、あとで分けるほうが大変になります。

SKILL.mdの本文には、500行という目安と、参照は1階層までという制約があります。ここでは、複数ファイルに分ける時、何をどこに置くかの基準を扱います。

置き場所は、内容の性質で決まります。

（出典: Anthropic公式ベストプラクティス）

scripts/に置いたコードは、実行結果だけがコンテキストに乗ります。コード自体は乗りません（出典: Anthropic公式Skills概要）。本文には「実行して」と「見て」のどちらを期待しているかを明記します。書かないと、読むだけでよいスクリプトの中身を、Claudeが本文にそのまま貼り付けることがあります。

10SKILL.mdから参照ファイルを分ける軸は、AIエージェントの無駄をどこで減らすんですか？

参照ファイルが100行を超える場合は、先頭に目次を置きます。部分的にしか読まれなかった時も、目次だけで全体をつかめるようにするためです（出典: Anthropic公式ベストプラクティス）。

複数の参照ファイルに分ける軸は、詳細度ではなく業務領域です。部署別に情報が増えるなら、1本のファイルにせず、references/sales.mdとreferences/engineering.mdのようにドメインで分けます。営業部の質問で、経理部の情報まで読み込む無駄を避けられます（出典: Anthropic公式ベストプラクティス）。

切り出しを検討するサインは3つです。

• 本文が500行に近づいている
• 同じ説明を、複数のセクションで繰り返している
• 部署や製品など、複数のドメインの知識が混ざっている

最終的なディレクトリは、次の形になります。

onboarding-checklist/
├── SKILL.md
├── templates/
│   └── standard.md
├── references/
│   └── department-notes.md
├── CONTRACTOR.md
└── scripts/
    └── validate_template.py

11SKILL.mdの書き方でつまずくのは、エージェントの何が見えていないからですか？

つまずきは3つに集まります。共通するのは、書き手の画面からは正しく見えている点です。

1つめは、説明を書きすぎることです。 Claudeが既に知っている前提を毎回言葉で説明し直すと、本文が長くなります。Anthropic公式が示す例では、同じ内容を丁寧に説明した本文は、簡潔な書き方の約3倍のトークンを使っていました（出典: Anthropic公式ベストプラクティス）。onboarding-checklistなら、テンプレートの選び方だけを書きます。チェックリストとは何かは書きません。

2つめは、参照を2階層以上にすることです。 SKILL.mdからadvanced.mdへ、advanced.mdからdetails.mdへと孫参照を作ると、Claudeはheadコマンドで先頭だけを読むことがあります。details.mdの情報に届かないまま処理が進みます（出典: Anthropic公式ベストプラクティス）。参照は、SKILL.mdから1階層にとどめます。

前後で入れ替わったのは、情報の量ではありません。届く保証のほうです。深い置き方でも、全部読まれれば同じ答えが出ます。読まれない時が混ざるだけです。

だから、この不具合は再現しにくい形で出ます。動く日もあれば、届かない日もある。原因を追いにくいのは、階層の深さそのものではなく、この当たり外れのほうです。

3つめは、実行してほしいのか読んでほしいのかを本文に書かないことです。 スクリプトへの言及だけでは、実行するのか参照するのかが伝わりません。「実行して」と「アルゴリズムはこのファイルを見て」を書き分けます（出典: Anthropic公式ベストプラクティス）。書き分けないと、決定的な処理のはずが、Claudeによる再生成に置き換わることがあります。

12書いたSKILL.mdが、AIエージェントに届いたかはどう確かめるんですか？

高梨課長

高梨課長の発言

書き終わったあと、どこまで確認すれば「できた」と言えるのでしょうか。

鈴木さん

鈴木さんの発言

3点だけ見ています。一覧に出るか、引数が展開されるか、参照ファイルが読まれるか。ここが通れば、最初の1本としては十分だと考えています。

書き終えたら、次の3点を確認します。

3点は並べて選ぶものではなく、順に積み上がっています。どこで落ちたかが、直す場所をそのまま指します。 一覧に出ないなら表紙、引数が展開されないなら綴り、参照が読まれないなら階層です。

1つめは、発火条件そのものの確認です。2つめは、引数付きで手動起動し、展開結果を目で確かめます。3つめは、業務委託のケースをわざと聞き、CONTRACTOR.mdの内容が答えに反映されるかを見ます。うまくいっている時といない時の見分けがつきにくいので、外れそうなケースを自分で作るところまでを確認に含めます。

数を測って発火精度を検証する方法は、Agent Skillsの発火精度｜59本の監査で見えた検証の組み立て方で扱っています。1本を書き終えた直後は、この3点の目視確認で足ります。

13よくある質問

14まとめ｜今日やる3つのこと

3段の順番は、フロントマター→本文→切り出しでした。3段が分かれているのは重要度ではなく、読み込まれるタイミングでした。そして書き終わりは、行数ではなく3点の目視確認で決まります。