SKILL.mdが長くなったら?手順と参照ファイルの分け方

長くなったSKILL.mdを整理したい。手順・参照・例外の分け方を解説するアイキャッチ画像

長くなったSKILL.mdは、判断に必要な入口を残し、作業別の詳細へ直接つなぐ構成に分けます。

スキルへ注意事項や成功例を足し続けたら、何ページもある説明書になった。「軽くしたい」とAIに頼むと、今度は大事な条件まで消されてしまう。そんなときは、文章の短縮より先にファイルの役割を整理します。

本文には「いつ使うか・何を選ぶか・どこまで行うか」を残し、選んだ作業の詳しい説明を参照ファイルへ移すのが基本です。この記事ではClaudeの公式資料をもとに、すでにあるスキルを分割する具体例を紹介します。以下の業務例と記載例は説明用に作成したもので、性能改善を実測した報告ではありません。

この記事でわかること

  • 内容の分類:SKILL.mdに残す内容と、参照ファイルへ移す内容
  • ファイル構成:分岐条件と相対パスを使った、迷いにくいファイル構成
  • 確認方法:分割後に起こりやすい参照漏れと確認方法

「軽くする」は、必要なときに詳しく読む構成へ変えること

SKILL.mdに共通条件と分岐を残し、必要な参照ファイルへ直接進む構成

ClaudeのAgent Skillsは、説明や本文、追加資料を段階的に読み込む仕組みを採用しています。追加資料を同梱できるため、長い見本をすべてSKILL.mdへ詰め込む必要はありません。公式資料では、この考え方をprogressive disclosureと呼んでいます。

ただし、別ファイルにしただけでは十分ではありません。本文で「最初にすべての参考資料を読む」と指示していたら、必要な部分を選ぶ構成にならないためです。どの条件なら、どのファイルを読むかまで一緒に書くことが大切です。

行数の目安を、品質の保証と取り違えない

Anthropicの作成ガイドは、SKILL.md本文を500行未満に保つことを目安として挙げています。これは、それ以下なら必ず正しく動くという合格基準ではありません。短くても参照先が分からなければ使いにくく、長さを減らすために確認条件を落とせば別の問題が起きます。

まずは、同じスキルに違う種類の作業が混ざっていないかを確認しましょう。たとえば問い合わせへの返信下書きと、回答済み案件の週次集計では、必要な入力も完成形も異なります。今回扱うのは、一つの仕事の中で必要な資料を分ける方法です。用途そのものが別なら、スキルを分ける判断もあります。

最初に、各段落の移動先を決める

ここでは「社内問い合わせの返信下書き」を作る架空のスキルを例にします。製品の使い方を答える場合と、契約内容の確認を担当者へ引き継ぐ場合があり、それぞれ長い回答見本が追加されている状態を考えます。実際の契約判断や送信は対象にしません。

今の本文にある内容 残す・移す場所 理由
問い合わせの返信下書きを作る用途 descriptionと本文の入口 スキルを選ぶために必要
入力不足なら確認事項を返す条件 SKILL.md 詳細資料を選ぶ前に判断する
製品操作の回答見本 references/product-reply.md 製品操作の質問にだけ必要
担当者へ引き継ぐ文面の見本 references/handoff-reply.md 引き継ぎが必要な場合に読む
根拠のない約束をしない・送信しない SKILL.md どの分岐でも守る条件

移す前に、重複と矛盾を見つける

見本の中に「必ず翌日回答」とあり、基本ルールには「期限を約束しない」とあれば、そのまま別ファイルへ移しても矛盾は残ります。まず採用するルールを決め、古い見本を修正または対象外として整理します。

移動一覧には「元の見出し」「移動先」「本文に残す参照条件」を並べます。全文の書き直しを先に頼むより、消してはいけない内容を点検しやすくなります。元の版は別名で保管し、新しい構成と取り違えないようにしてください。

3つのファイルで、分岐と参照先をつなぐ

本文には、判断と参照先の対応を置く

フォルダ内にSKILL.mdを置き、referencesフォルダへ2つの参考資料を置きます。次はSKILL.mdの本文部分へ入れる記載例です。既存の名前やdescriptionを含む先頭の設定部分を、これだけで置き換えないでください。

## 入力の確認
問い合わせ本文と、回答の根拠になる社内資料を確認する。
根拠がない場合は答えを補わず、不足情報を返す。

## 作業の選択
- 製品操作の説明を求められた場合は、[操作案内の見本](references/product-reply.md)を読む。
- 担当者への引き継ぎが必要な場合は、[引き継ぎ文面の見本](references/handoff-reply.md)を読む。
- 両方に該当する場合は両方を読み、回答できる部分と確認が必要な部分を分ける。

## 共通の完了条件
根拠資料と下書きを照合し、未確認の内容を明示する。
資料にない期限・対応・契約上の約束を作らない。
下書きの提示までとし、外部送信は行わない。

この例で重要なのは「必要なら資料を読む」という一文で済ませていない点です。質問の種類とファイルを対応させているため、次に進む場所が分かります。全分岐で守る条件を、特定の見本の奥だけに置かないようにします。

参照側には、具体的な見本と注意点をまとめる

product-reply.mdには、操作案内の構成、短い入出力例、間違えやすい製品用語を置きます。handoff-reply.mdには、回答を保留する際の構成、担当者へ渡す確認事項の例を置きます。顧客名や実際の契約情報を汎用見本へ埋め込まないようにしてください。

たとえば操作案内の見本なら、「確認できた操作」「操作前の条件」「できない場合の相談先」を並べる程度から始められます。見本は構成を示すものに留め、実在製品の仕様や期限を架空で補いません。

参照を何段もたどらせない

公式ガイドは、SKILL.mdから参照ファイルへ直接つなぐ、1段階の参照を勧めています。本文から目次ファイル、目次から分類ファイル、そこから本当の手順へ進む構成は避け、入口に読むべき資料を示しましょう。長い参照ファイルには冒頭の目次を付ける方法も案内されています。

ファイル名を変更したら、本文に書いた相対パスも更新します。フォルダ内に資料が存在していても、本文が以前の名前を指していたら参照できません。ZIPで持ち運ぶ場合は、展開後のフォルダにも同じ資料が入っているか確認します。

分割後は、参照漏れを小さな入力で確かめる

操作案内・引き継ぎ・両方の3ケースを試す

今回の例なら、製品操作だけの質問、担当者への確認だけが必要な質問、その両方が混ざる質問を用意します。元の版と分割版に同じ架空入力を渡し、下書きの必要項目が残っているかを見ます。

出力に引き継ぎ文面がない場合は、単に「もっと丁寧に」と追記する前に、分岐条件が曖昧でなかったか、参照ファイル名が正しいかを確認します。環境に参照記録が表示されるなら実際に開いたファイルも調べます。AIの「読みました」という説明だけで、参照が成功したと判断しないことが大切です。

文字数が減っただけで、速くなった、費用が下がった、精度が上がったとは言えません。まず確認したいのは、必要な資料へ進めることと、移動前の条件が失われていないことです。

まだスキルを作っていない場合は、ClaudeのSkillsを会議メモ整理から作る手順が出発点になります。この記事の分割は、作成後に説明が増えた段階の整理に使ってください。

実務上の注意

参照ファイルへ移すことは、情報を秘密にすることではありません。スキルを共有する際は、同梱する資料も含めて取り扱いを確認します。また、ファイルの分割だけを目的に、実行スクリプトや外部接続を追加する必要はありません。利用するClaudeの画面・Code・APIによって登録や利用方法は異なるため、構成の整理と利用環境の設定を分けて確認してください。

まとめ

SKILL.mdを軽くするときは、まず内容の置き場所を決めます。本文に判断と共通条件を残し、分岐別の詳細へ直接リンクすると、何を読むべきか分かりやすくなります。分割後は同じ入力で必要項目と参照先を確認し、短さだけで完成扱いにしないようにしましょう。

よくある質問

500行を超えたらスキルは動かなくなりますか?

ここで紹介した500行未満は、公式作成ガイドの推奨目安です。動作の可否を一律に決める上限として扱わず、内容の役割や利用環境の制限も確認してください。

参照ファイルは、フォルダに入れるだけで読まれますか?

本文から参照先と読む条件を示してください。必要な資料が同梱されていることと、実行時に適切に参照されたことは別に確認します。

禁止事項も別ファイルへ移してよいですか?

どの作業でも守る重要な境界は、本文の共通条件として残すと確認しやすくなります。特定作業だけの詳細な注意は、その参照資料に置けます。

出典・参考情報

運営元について

AXメディアは、株式会社ジーズ AX事業部が運営しています。AX事業部では、AI研修・AIエージェント開発・ローカルLLM開発・補助金/助成金の活用支援を提供しています。

AX事業部のサービスを見る

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

この記事を書いた人

AXメディア編集部のアバター AXメディア編集部 AXメディア公式編集部

AXメディア編集部は、株式会社ジーズ(東京都豊島区、2013年6月設立)のAX事業部が運営する実務向けAIメディア「AXメディア」の公式編集チームです。生成AIの業務での使い方、企業への導入の進め方、情報漏洩を防ぐ運用の注意点を、公式情報と社内での検証をもとに記事にしています。運営会社はAIO診断・AI研修・補助金活用支援なども手がけています。編集責任者はAXメディア ディレクターのこおじです。訂正のご連絡は info@ax.gsgs.co.jp までお願いします。