SKILL.mdの書き方仕様・パターン・実例
SKILL.mdはAgent Skillの「顔」です。YAMLフロントマターの2フィールドがSkillの発見精度を決定づけ、本文の記述パターンがタスク遂行の品質を左右します。本記事では仕様・パターン・実例を通じて、確実に機能するSKILL.mdの書き方を体系的に解説します。
SKILL.mdとは、Agent Skillの仕様・指示・ワークフローを定義するMarkdownファイルです。YAMLフロントマターによるメタデータとMarkdown本文による指示を1ファイルに統合し、AIエージェントが「いつ・どのように」そのSkillを使うかを制御します。
この記事で学べること
前提知識: Part 1（Skillsとは何か）の内容、特に段階的開示（Progressive Disclosure）の概念とSKILL.mdの位置づけを理解していると読みやすい構成です。
YAMLフロントマター — Skillの「顔」
Part 1で解説した段階的開示を思い出してください。Claudeが起動時に読み込むのは、各Skillのnameとdescriptionだけです。100個のSkillが登録されていても、Claudeはフロントマターの情報だけを頼りに「今このタスクにはどのSkillが適切か」を判断します。
重要: フロントマターの品質がSkillの利用頻度と精度を直接左右します。ここが曖昧だと、本来使われるべきシーンでSkillが発動しません。
必須フィールド
SKILL.mdの冒頭には、YAMLフロントマターとしてnameとdescriptionの2つのフィールドが必須です。
# SKILL.md — 最小限のフロントマター
--- name: pdf-processing description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. ---
YAMLフロントマターとは、ファイル冒頭の---で囲まれた領域に記述するメタデータのことです。Markdownファイルに構造化された情報を埋め込むための標準的な形式で、多くの静的サイトジェネレーターでも採用されています。
nameフィールドの仕様
| ルール | 詳細 |
|---|---|
| 文字数 | 1〜64文字 |
| 使用可能文字 | 小文字英数字とハイフンのみ（a-z, 0-9, -） |
| ハイフン制約 | 先頭・末尾不可、連続（--）不可 |
| ディレクトリ名との一致 | 必須（name: pdf-processing なら親ディレクトリも pdf-processing/） |
| 予約語 | anthropic, claude は使用不可 |
pdf-processing, data-analysis, code-review, commit-message
PDF-Processing（大文字）, -pdf（先頭ハイフン）, pdf--processing（連続ハイフン）, claude-helper（予約語）
Best Practice
Anthropic公式は動名詞形（verb + -ing）を推奨しています。processing-pdfs、analyzing-spreadsheetsのように、Skillが「何をするか」が名前から直感的に分かる形式です。helper、utilsのような汎用名は他のSkillと競合しやすいため避けましょう。
descriptionフィールドの仕様と書き方
descriptionはSkillの発見精度を決定づける最重要フィールドです。Claudeは100以上のSkillの中から、descriptionだけを頼りに適切なSkillを選択します。
| ルール | 詳細 |
|---|---|
| 文字数 | 1〜1,024文字 |
| 視点 | 三人称で記述（システムプロンプトに注入されるため） |
| 内容 | 「何をするか」＋「いつ使うか」の両方を含める |
なぜ三人称で書くのか？
descriptionはClaudeのシステムプロンプトにそのまま注入されます。一人称や二人称で書くと、Claudeの「人格」や指示文脈と噛み合わず、発見精度の低下につながります。
description: Processes Excel files and generates reports
→ システムプロンプトに自然に統合される
description: I can help you process Excel files
→ Claudeの「人格」と混同する
description: You can use this to process Excel files
→ 指示文脈と噛み合わない
良い例と悪い例の対比
| 品質 | description | 評価理由 |
|---|---|---|
| ✅ | Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files. | 具体的な動作＋トリガーキーワードが豊富 |
| ✅ | Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes. | ユースケースが明確 |
| ✕ | Helps with documents | 曖昧すぎて何にマッチするか不明 |
| ✕ | Processes data | 具体性がなくどのタスクとも区別できない |
homula's Insight
良いdescriptionの共通点は、「何をするか」（具体的な動作の列挙）と「いつ使うか」（トリガーとなる状況やキーワード）の両方を明示していることです。ユーザーがどのような言い回しでリクエストするかを想像し、それに引っかかるキーワードを含めることがSkill設計の肝です。
オプションフィールド
必須フィールドに加えて、以下のオプションフィールドを指定できます。
# オプションフィールドを含むフロントマター
--- name: pdf-processing description: Extract text and tables from PDF files... license: Apache-2.0 compatibility: Requires poppler-utils for PDF rendering metadata: author: example-org version: "1.0" allowed-tools: bash read write ---
| フィールド | 用途 | 記載例 |
|---|---|---|
| license | ライセンス情報 | Apache-2.0 |
| compatibility | 動作環境の要件（最大500文字） | Requires git, docker, jq |
| metadata | 任意のキー・バリュー | author, version, tags 等 |
| allowed-tools | ツールの事前許可リスト | bash read write（実験的機能） |
Markdown本文 — 4つの記述パターン
フロントマター以降の本文はMarkdownで記述します。構造や形式に関する公式の厳密な制約はありませんが、だからこそ設計力が問われる部分です。まず基本原則を押さえた上で、タスクの性質に応じた4つの記述パターンを紹介します。
基本原則
500行
推奨行数上限
超える場合はreferences/ディレクトリに詳細を分割
1箇所
情報の記載箇所
SKILL.mdと参照ファイルで情報を重複させない
1階層
参照の深さ上限
参照ファイルからさらに別ファイルを参照する深いネストは避ける
テンプレート型（厳密な指示）
フォーマット固定の出力 — コミットメッセージ、定型レポート、コーディング規約
出力の形式を厳密に規定するパターンです。Claudeに「判断の余地」を与えず、確実に一定の形式で出力させたい場合に選びます。
## Commit Message Format
Generate commit messages following Conventional Commits:
`type(scope): description`
### Types
- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- refactor: Code restructuring
### Rules
- Subject line: max 50 characters
- Body: wrap at 72 characters
- Use imperative mood ("add" not "added")ガイドライン型（柔軟な指示）
判断・分析を伴うタスク — コードレビュー、競合分析、レポート作成
「デフォルトの構造」を示しつつも、Claudeの推論能力を活かして文脈に応じた調整を認めるパターンです。マイクロマネジメント的な指示よりも「何を達成すべきか」を伝えるアプローチの方が良い結果を生むケースが多くあります。
## Report Structure Here is a sensible default format, but use your best judgment based on the analysis: 1. Executive Summary — key takeaway in 2-3 sentences 2. Key Findings — adapt sections based on what you discover 3. Recommendations — tailor to the specific context Adjust sections as needed for the specific analysis type. The goal is clarity, not rigid adherence to a template.
Examples型（入出力例）
スタイル統一が重要 — ドキュメント、命名規則、文体の統一
言葉で説明するよりも「こういう入力にはこういう出力」という例を見せた方が効果的なパターンです。3つ程度の具体的な入出力ペアを提示するのが最適で、バリエーションを網羅するように例を選びます。
## Commit Message Examples **Example 1:** Input: Added user authentication with JWT tokens Output: feat(auth): implement JWT-based authentication **Example 2:** Input: Fixed bug where dates displayed incorrectly Output: fix(reports): correct date formatting **Example 3:** Input: Updated dependencies and refactored error handling Output: chore: update dependencies and refactor error handling Follow this style: type(scope): brief description.
なぜ3例がベストか：1つでは偶然に見え、5つ以上ではトークンを消費しすぎます。機能追加・バグ修正・メンテナンス等のバリエーションを網羅する3例が、精度とトークン効率のバランスポイントです。
Decision Tree型（条件分岐ワークフロー）
判断ポイントがある複合タスク — ドキュメント変換、エラー対応、承認フロー
入力の状態によって処理の流れが分岐するタスクに適したパターンです。複雑化した場合は、各分岐先のワークフローを別ファイルに分割することも有効です。
## Document Modification Workflow 1. Determine the modification type: **Creating new content?** → Follow "Creation workflow" **Editing existing content?** → Follow "Editing workflow" 2. Creation workflow: - Use docx-js library - Build document from scratch - Export to .docx format 3. Editing workflow: - Unpack existing document - Modify XML directly - Validate after each change - Repack when complete
パターン選択ガイド
タスクの性質を判定:
フォーマット固定？ ─── Yes ──→ ① テンプレート型
│
No
│
判断・分析を伴う？ ─── Yes ──→ ② ガイドライン型
│
No
│
スタイル統一が重要？ ── Yes ──→ ③ Examples型
│
No
│
条件分岐がある？ ──── Yes ──→ ④ Decision Tree型
│
No
│
複合的なタスク？ ──── Yes ──→ 複数パターンを組み合わせ
例: レポート作成 = ①+②+③homula's Insight
homulaの支援実績では、エンタープライズのSKILL.md設計は単一パターンで完結することは稀です。複数パターンの組み合わせが標準であり、最適な組み合わせの設計がSkillの品質を大きく左右します。
実践サンプル
そのままコピペして使える2つのサンプルを紹介します。最小構成と参照ファイルを持つ実用的な構成の2パターンです。
最小構成（SKILL.mdのみ）
コミットメッセージ生成Skillの完全な例です。この内容をそのままcommit-message/SKILL.mdとして保存すれば、動作するSkillが完成します。
# commit-message/SKILL.md
--- name: commit-message description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes. --- # Commit Message Generator ## Process 1. Run `git diff --staged` to see changes 2. Identify the primary change type 3. Write a concise subject line (max 50 chars) 4. Add body with details if the change is complex ## Format Follow Conventional Commits: `type(scope): description` ## Types - feat: New feature - fix: Bug fix - docs: Documentation - refactor: Restructuring - test: Tests - chore: Maintenance
このサンプルのポイント
descriptionに「何をするか」（Generate descriptive commit messages by analyzing git diffs）と「いつ使うか」（when the user asks for help writing commit messages）の両方が含まれています。
本文はプロセス→形式→タイプ一覧という論理的な順序で構成されており、Claudeが手順を迷わず実行できる構造です。
サイズは全体で数十行に収まっており、SKILL.md単体で完結しています。
参照ファイルを持つ構成
データウェアハウスのクエリ生成Skillです。テーブル定義が多いため、SKILL.mdにはワークフロー概要だけを置き、詳細をreferences/に分割しています。
sql-analysis/
├── SKILL.md
└── references/
├── finance.md # 財務テーブルのスキーマ・クエリパターン
├── product.md # プロダクト利用テーブル
├── sales.md # 営業パイプライン
└── customers.md # 顧客データ定義# sql-analysis/SKILL.md
# Data Warehouse Query Skill ## Overview Generate accurate SQL queries against our data warehouse. Always filter out test accounts and use complete periods only. ## Table References - For finance queries, read `references/finance.md` - For product usage data, read `references/product.md` - For sales pipeline, read `references/sales.md` - For customer metrics, read `references/customers.md` ## General Rules - Always use UTC timestamps - Exclude rows where `is_test_account = true` - Use complete calendar periods only (no partial months)
段階的開示の動作イメージ
ユーザー: 「先月の売上を集計して」
│
▼
[Claude] SKILL.md を読み込み
│ → finance.md が必要と判断
▼
[Claude] references/finance.md を読み込み
│ ✗ product.md — 読み込まない
│ ✗ sales.md — 読み込まない
│ ✗ customers.md — 読み込まない
▼
[Claude] SQLクエリを生成・実行
→ 必要な参照ファイルだけがコンテキストに読み込まれ
トークン消費を最小化落とし穴: MCPツールの参照方法
SkillからMCP（Model Context Protocol）サーバーのツールを利用する場合、注意すべき命名規則があります。MCPとはAIアシスタントと外部システムを接続するためのオープン標準プロトコルで、詳細はMCP活用ガイドで解説していますが、ここではSkillから参照する際の実務上のポイントに絞って説明します。
サーバー名:ツール名 の形式が必須
MCPツールを参照する際は、必ずサーバー名:ツール名の形式で記述してください。
# MCPツール参照の正しい形式
## Tool References - Use the `BigQuery:bigquery_schema` tool to inspect table schemas - Use the `GitHub:create_issue` tool to create issues
注意: プレフィックス（サーバー名）を省略すると、複数のMCPサーバーが接続されている環境でClaudeがツールを特定できず、エラーの原因になります。
パッケージのインストールを明示する
Skillが外部パッケージを必要とする場合、「入っているはず」と仮定してはいけません。インストール手順を明示的に記述しましょう。
Use the pdf library to process the file.
Install required package:
`pip install pypdf`
Then use it:
from pypdf import PdfReader
reader = PdfReader("file.pdf")まとめ
フロントマターが発見精度を決める
nameは小文字英数字＋ハイフンで動名詞形を推奨。descriptionは三人称で「何をするか」＋「いつ使うか」を明示し、トリガーキーワードを豊富に盛り込む。
4つの記述パターンを使い分ける
テンプレート型（フォーマット固定）、ガイドライン型（判断・分析）、Examples型（スタイル統一）、Decision Tree型（条件分岐）。複合タスクでは組み合わせも有効。
500行ルールとreferences/分割
SKILL.mdはナビゲーション役に徹し、詳細はreferences/に分割。情報重複を避け、参照は1階層に留める。
MCP参照と依存関係の明示
MCPツールは「サーバー名:ツール名」形式で記述。外部パッケージは必ずインストール手順を含める。
homulaの支援体制
homulaは、エンタープライズ企業向けにAIエージェントの戦略策定・PoC・実装・運用・内製化までを一気通貫で支援するAIインテグレーターです。SKILL.md設計を含むエージェント構築を、以下のサービスで支援しています。
シリーズナビゲーション
関連ガイド
よくある質問
技術的には日本語でも動作しますが、Claudeのシステムプロンプトへの統合精度を考慮すると英語が推奨です。descriptionはClaudeがSkillを「発見」するための検索キーワードとして機能するため、ユーザーの指示言語とマッチしやすい英語の方が発見精度が高くなります。本文（Markdown部分）は日本語でも問題ありません。
出力フォーマットが固定ならテンプレート型、判断・分析を伴うならガイドライン型、スタイル統一が重要ならExamples型、条件分岐があるならDecision Tree型が適しています。実際のSkillでは複数パターンの組み合わせも有効です。例えばレポート作成なら、出力形式はテンプレート型で固定しつつ分析方法はガイドライン型で柔軟に対応する構成が考えられます。
references/ディレクトリに詳細を分割してください。SKILL.mdは「何をどこで見るか」を案内するナビゲーション役に徹し、テーブルスキーマ・API仕様・詳細ルールなどは参照ファイルに配置します。これにより段階的開示が効果的に機能し、必要な参照ファイルだけがコンテキストに読み込まれるためトークン効率も向上します。
MCPツールを参照する際は、必ず「サーバー名:ツール名」の形式（例: GitHub:create_issue）で記述してください。サーバー名（プレフィックス）を省略すると、複数のMCPサーバーが接続された環境でClaudeがツールを特定できずエラーの原因になります。また、外部パッケージを使用する場合はインストール手順も明示的に記載します。
homulaは、エンタープライズ向けにAIエージェントの戦略策定からPoC・実装・運用までを一気通貫で支援しています。SKILL.md設計を含むエージェント構築は、5日間のブートキャンプで動くプロトタイプを構築するところから始められます。組織固有のナレッジをSkill化し、品質の一貫性とスケーラビリティを実現するノウハウを提供しています。
Skills設計を含むAIエージェント構築を始めませんか？
homulaは、SKILL.md設計を含むAIエージェントの戦略策定からPoC・実装・運用までを一気通貫で支援します。5日間のブートキャンプで、動くプロトタイプとROI試算を構築できます。