AIエージェントのためのSKILL.mdとツール説明をMarkdownで記述する方法

AIアシスタントが明確な指示に従い、特定の知識領域を読み込み、外部ツールを安全に呼び出せるようになったとき、その真の価値が発揮されます。Markdownはこれらの設定や指示を記述するのに最適な形式です。なぜなら、人間にとっての可読性やGitによるバージョン管理のしやすさを維持しつつ、大規模言語モデル（LLM）にとっても正確に解析できる論理構造を備えているからです。

この記事では、Markdownを使用したエージェントのスキル定義ファイル（SKILL.md）、エージェント指示ファイル、およびツール定義の書き方を解説します。その目的は、プロンプトを単に長くすることではありません。AIエージェントが必要な機能を簡単に見つけ、正しく理解し、適切なタイミングで実行できるようにすることにあります。

SKILL.md ファイルとは何か

SKILL.md ファイルとは、再利用可能な特定の機能（スキル）の手順やルールを記述したMarkdownドキュメントです。たとえば、Anthropicが提供する Claude Code などのエージェントシステムでは、スキルはファイルシステム上の特定のディレクトリに配置され、それぞれが SKILL.md ファイルによって定義されます。異なるエージェントフレームワークであっても基本的な考え方は同じです。**「エージェントはどのような状況でこの機能を使うべきか」「実行する際の具体的なワークフローは何か」「関連するスクリプトや参照資料はどこにあるのか」**を整理した、シンプルで構造化されたマニュアルです。

AIとのやり取りにおいては、次のようなメンタルモデルで整理すると理解しやすいでしょう。

• 通常のプロンプト：AIに「今この瞬間」に何をすべきかを指示する。
• スキル（SKILL.md）：AIに「特定のカテゴリのタスク」を今後繰り返し実行する方法を教える。
• ツールの説明（Tool Description）：AIに「特定の外部関数やAPI」をいつ、どう呼び出すべきかを教える。

スキル定義の大部分は、具体的な手順、制約事項、サンプル、参照リンクで構成されるため、Markdown記法が最も自然にフィットします。

なぜMarkdownはエージェントスキルに向いているのか

エージェントへの指示ファイルは、「AIモデル」と「人間の管理者」という2つの異なる読者を満足させる必要があります。Markdownはその両方をカバーできます。

AIに対しては、見出しやリストがトリガー条件、手順、制約、具体例、エラー発生時の代替アクションを明確に区切るガイドラインとなります。人間に対しては、Gitで変更内容を追跡（Review）し、任意のテキストエディタで編集し、ソースコードと同じリポジトリ内でドキュメントとして一元管理できるという恩恵をもたらします。

これは、スキルやツールの設計において特に重要です。曖昧な指示は、プログラムの自動化ワークフローにおいて重大なミスを引き起こすからです。曖昧なスキルは誤ったタイミングで起動し、不正確なツール説明は間違ったパラメータでのAPI呼び出しを誘発します。安全対策のメモが欠けていれば、エージェントは十分な事実確認を行わずに重要な変更を実行してしまうかもしれません。

スキル（Skills）とツール説明（Tool Descriptions）の違い

スキルとツールは密接に関連していますが、その役割とレベルが異なります。

| 項目 | 目的・役割 | 具体例 | |---|---|---| | スキル (Skill) | 再利用可能なワークフローや特定の業務手順を教える | 「プルリクエストのコードレビュー手順」 | | ツールの説明 (Tool) | 呼び出し可能なプログラム関数の機能とパラメータを伝える | 「GitHub Issuesをキーワードで検索する」 | | システムプロンプト | アシスタント全体の役割や基本的なトーンを設定する | 「簡潔に回答し、事実の裏付けを必ず確認すること」 | | プロジェクト指示書 | リポジトリ独自のコーディング規約や制約を説明する | 「pnpmを使用し、許可なくビルドを実行しないこと」 |

OpenAIのFunction Calling（関数呼び出し）や各種エージェントSDKのドキュメントでは、ツールはモデルが外部データにアクセスし、APIを叩き、コードを実行するための「窓口」として説明されています。公式ガイドでは、「ツールが何をするのか」「どのような状況で呼び出されるべきか」を説明する、短く明確な説明文を書くことが推奨されています。この原則はMarkdownのスキル定義にもそのまま当てはまります。トリガーと用途を極めて具体的に定義しましょう。

実践的な SKILL.md の構造テンプレート

効果的なスキルファイルは、以下の6つの質問に明確に答える必要があります。

1. このスキルはどのような機能を提供するのか？
2. エージェントはこれをどのような状況で起動すべきか？
3. どのような状況ではこのスキルを使用すべきではないか？
4. エージェントが実行すべき具体的なワークフロー（手順）は何か？
5. 利用可能なローカルファイル、スクリプト、参照資料は何か？
6. 最終的な出力はどのような形式であるべきか？

以下は、そのまま活用できる標準テンプレートです。

---
name: markdown-conversion-review
description: PDF、Word、HTML、Officeファイルから変換されたMarkdownドキュメントのレビューやクレンジングを行う際に使用するスキル。
---

# 技能名：Markdown変換品質レビュー

## 起動条件 (Use This Skill When)
- ユーザーから、変換されたMarkdownのクレンジングや改善を求められたとき。
- ドキュメントをREADME、公式ドキュメント、ブログ、またはAIプロンプトのコンテキスト用として整備するとき。
- 変換元のファイルから抽出されたテーブル、見出し、リンク、コードブロックの修復が必要なとき。

## 除外条件 (Do Not Use This Skill When)
- ユーザーが単にMarkdown記法の基本的な仕様や書き方について質問しているとき。
- 対象となるファイル以外の、無関係なソースコードの書き換えが必要なとき。

## 標準ワークフロー (Workflow)
1. **構造チェック**: 変換後のMarkdownに、見出し階層の崩れ、テーブルの破損、リンク切れ、コードブロックの閉め忘れがないか確認します。
2. **意味の維持**: クレンジング作業中は、ユーザーから明確な書き換えの指示がない限り、元の文章の意味や順序を厳密に維持します。
3. **Markdownの正規化**: 標準的でシンプルなMarkdownの記法を使用して、見出し、リスト、ハイパーリンク、テーブルのレイアウトを整理します。
4. **限界の明記**: 元のドキュメントの構造上、どうしてもきれいに再現できないレイアウトがある場合は、ファイルの最後に注意書きとして記録します。
5. **最終出力**: クレンジング済みのMarkdownテキストと、主要な変更点のメモをユーザーに返します。

## 品質基準・制約 (Quality Bar)
- 元ファイルに存在しない情報を絶対に捏造しないこと。
- コードブロックの中身は、明示的な変更指示がない限り元のコードをそのまま維持すること。
- 複雑なHTMLタグの埋め込みを避け、シンプルな標準Markdownを最優先すること。

## 期待する出力形式 (Output Format)
以下の順序で返却してください：
1. 修正・クレンジング済みのMarkdownテキスト
2. 主要な変換に関する対応メモ
3. 再現できなかったレイアウトや未解決の課題リスト

上記の Frontmatter（前置データ）フィールドは、使用するエージェントシステム（Claude Codeなど）の仕様に合わせて調整します。ドキュメント本文の構成（起動条件、除外条件、手順、品質基準、出力形式）はあらゆるプラットフォームで共通して有効です。

優れた説明文（Description）を書くコツ

スキルやツールの定義において、description フィールドは最も重要な項目です。なぜなら、エージェントはこの短い説明文をもとに「このスキルが現在のタスクに適しているか」をセマンティックに判断するからです。

悪い説明文の例：

description: Markdownの処理を助けます。

良い説明文の例：

description: 変換されたMarkdownドキュメントのクレンジング、レイアウトの正規化が必要な場合、あるいはドキュメントをプロジェクトのREADME、開発ドキュメント、ブログ記事、またはAIプロンプトのコンテキスト用に最適化する際にこのスキルを呼び出します。

優れた説明文には以下の要素が含まれています：

• 起動する状況：「～が必要な場合、あるいは～する際に」
• 具体的な処理：「クレンジング、レイアウトの正規化、最適化」
• 対象オブジェクト：「変換されたMarkdownドキュメント」
• 想定ユースケース：「README、開発ドキュメント、ブログ記事、またはAIプロンプトのコンテキスト用」

ツール定義の説明文の書き方

ツールの説明は、スキルファイルよりもさらに短く凝縮した記述が求められます。ツールは特定のプログラム関数を指すため、AIが必要とする情報は極めてシンプルです。

• このツールは何をするのか？
• どのようなパラメータを要求するのか？
• どのような結果を返すのか？

JSON形式でのツール定義例：

{
  "name": "convert_file_to_markdown",
  "description": "アップロードされたPDF、DOCX、PPTX、XLSX、HTML、または画像ファイルをMarkdownに変換します。編集可能なテキストや、AIでの分析パイプラインに適した構造化ドキュメントを作成したい場合に使用します。",
  "parameters": {
    "type": "object",
    "properties": {
      "file_id": {
        "type": "string",
        "description": "変換対象となるアップロードファイルのユニークなID。"
      },
      "preserve_tables": {
        "type": "boolean",
        "description": "ドキュメント内の表を、可能な限りMarkdownのテーブル形式として抽出・変換するかどうか。デフォルトはtrue。"
      }
    },
    "required": ["file_id"]
  }
}

この定義には無駄な修飾語がなく、サポートするファイル拡張子、トリガーとなるユーザーの目的、そして各パラメータの意味が実務的に記述されています。これにより、エージェントによる誤呼び出しを防ぎ、引数のエラーを最小限に抑えることができます。

ツールドキュメントをMarkdownで整備するメリット

コード内で定義された多数のAPIツールが存在する場合、それらの「利用ガイド」をMarkdownでまとめておくことは、AIの挙動を安定させる上で非常に有効です。

# ツール仕様書：convert_file_to_markdown

## 目的
サポートされているドキュメントファイルをMarkdown形式に変換します。

## 呼び出すべきシナリオ
- ユーザーがファイルをアップロードし、Markdownへの変換を直接求めているとき。
- ユーザーがファイルコンテンツをLLM分析、README生成、ドキュメントページ作成、ブログ下書きとして活用したいとき。

## 呼び出してはならないシナリオ
- ユーザーが単にMarkdownに関する一般的な技術仕様を質問しているとき。
- 入力ファイルが既にきれいなMarkdownであり、追加の変換が必要ないとき。

## 入力パラメータ
| パラメータ名 | データ型 | 必須フラグ | 説明・備考 |
|---|---|---:|---|
| file_id | string | 必須 | アップロードファイルの識別ID |
| preserve_tables | boolean | 任意 | 表（テーブル）の構造を極力維持するかどうか |

## 期待される出力結果
変換されたMarkdownテキスト、および変換時の処理メモ。

## エラー発生時の挙動
- サポート外のファイル形式が渡された場合、対応フォーマットの一覧を提示します。
- レイアウトの維持が難しい場合、抽出できたベストなテキストデータを返し、制限事項を説明します。

ツールの定義自体はプログラムで実装されているものの、エージェントがより安全かつ高度にツールを操作できるようにする「運用ガイドライン」として効果的です。

エージェントにとって「使いやすいスキル」の条件

良いスキルファイルは、実務上の判断を助ける具体的な記述に満ちています。

1. 起動条件の解像度が高い

抽象的な見出しだけで済ませず、具体的なタスクの性質を指定します。

悪い例：

# SEOスキル

良い例：

## 起動条件
- ユーザーから、特定のWebページの検索パフォーマンス（SEO）改善を求められたとき。
- メタタイトル、メタディスクリプション、適切な見出し（H2/H3）、内部リンク、あるいはFAQセクションの追加・修正が必要なとき。
- ユーザーが Google の E-E-A-T 原則、有用なコンテンツ（Helpful Content）、または品質改善ガイドラインに言及したとき。

2. 非目標（Non-Goals）を明記している

「やってはいけないこと」を明記することは、エージェントが暴走したり誤った提案をしたりするのを防ぐ最強のブレーキになります。

## 禁止事項 (Do Not)
- 法律、医療、あるいは金融などの専門的資格が必要なアドバイスを提供すること。
- 架空の顧客レビュー、虚偽の統計データ、偽の参考文献、あるいは実績データを捏造すること。
- 対象となるWebページのトピックが、ユーザーが求めている製品価値や実際の意図と乖離していること。

3. アクション重視の具体的な手順

作業のステップを箇条書きで示します。あまり細かすぎて柔軟性を失わない程度に、しかし確実に実行すべきチェックポイントを含めます。

4. 「良い例」と「悪い例」の対比

AIへの指示において、具体的な文章のサンプルを示すことは、何十行もの抽象的なルールを書くよりも効果的です。

## 文案トーンのサンプル

- **避けるべき表現（悪い例）**：
  「当社の革新的なコンバーターは、あらゆるファイルの完璧な変換を100%保証します。」
  *(理由：誇大表現であり、ユーザーの信頼を損なうリスクがある。)*

- **推奨する表現（良い例）**：
  「このコンバーターは、元のファイルをMarkdownテキストとして抽出します。元のファイルが見出し、リスト、および標準的な表で整理されている場合に、最も高い精度で変換できます。」
  *(理由：事実に基づき、利点と限界の両方を誠実に説明している。)*

5. 安全境界と権限の明記

特にローカル環境でスクリプトを実行したり、ファイルを書き換えたりする機能を持つスキルの場合、権限の限界を明確に定義しておく必要があります。

## 安全境界とファイル操作
- ファイルを書き換える（編集する）前に、必ずファイル全体を一度読み込んで確認すること。
- ユーザーのファイルを削除する際は、必ずユーザーの明示的な許可をチャット上で得ること。
- 不明な外部APIや外部サーバーにデータを送信する前に、必ず確認を求めること。

設計時によくある間違い

• 間違い 1：1つのスキルに機能を詰め込みすぎる：1つのスキルは1つのまとまったテーマに絞るべきです。SEO、アクセス解析、文案作成、プライバシーポリシー審査、メール送信をすべて1つの「マーケティングスキル」に詰め込むと、エージェントはどれを使うべきか混乱します。
• 間違い 2：抽象的な理想論を書く：「世界一流のテキストを書いてください」や「魅力的なデザインにしてください」といった指示はAIにとって評価基準がありません。「ソースリンクを明記する」「字数を150字以内に収める」といった観察可能な要件に置き換えましょう。
• 間違い 3：重要なルールを長い段落の中に埋もれさせる：エージェントも人間と同様に、長い段落の真ん中にあるルールよりも、箇条書き（Bullet points）で書かれたルールを圧倒的に重視します。
• 間違い 4：エラー時の処理が抜けている：APIはタイムアウトし、インプットファイルは途中で切れることがあります。「失敗したときにAIが次に取るべき行動」を必ずスキルに含めておきましょう。

まとめ

Markdownで記述する SKILL.md やツールの説明は、AIエージェントの挙動をコントロールし、安全に運用するための最も合理的でメンテナンスしやすいインフラです。

もしあなたがドキュメント変換、AIナレッジベース、あるいはカスタムAIアシスタントのワークフローを設計しているなら、記述ルールを統一した SKILL.md の整備は、人間側の意図をAIエージェントに正確に伝えるための最初の一歩になります。

参考資料と推奨文献

• Claude Docs: エージェントスキルの設計
• Claude Code ガイド：エージェントSDKでのスキル
• OpenAI API：Function Calling 開発リファレンス
• OpenAI Agents SDK (Python/JavaScript) ツールガイド