エージェント スキル オーサリング ガイド

これは高品質な SKILL.md ファイルを作成するための権威的なリファレンスです。ユーザーがスキルの作成、編集、改善を依頼した場合、これらの指示に従って、あらゆるコンシューマーエージェントが発見、有効化、効果的に適用できる最高の結果を生成します。

---

1. コア原則

これらの原則は Anthropic の公式ベストプラクティスに基づいています。すべてのスキルに適用します。

Claude は既に非常に賢いです。 Claude が既に持っていないコンテキストのみを追加してください。各コンテンツに異議を唱えます。「Claude は本当にこの説明が必要ですか？」「Claude がこれを知っていると仮定できますか？」「このパラグラフはトークンコストに見合う価値がありますか？」 簡潔なスキルはコンテキストウィンドウが会話履歴、システムプロンプト、および他のスキルのメタデータと共有されるため、より良いパフォーマンスを発揮します。

「何」ではなく「なぜ」を説明します。 Anthropic のガイダンス：「重くて古い MUST ではなく、なぜ物事が重要なのかをモデルに説明します。」エージェントが推論を理解すると、新しい状況全体で正しく一般化します。命令的なルールのみの硬直した方法は、脆く、過度に文字通りの行動を引き起こします。

脆さと特異性を一致させます。 複数のアプローチが有効である場合は、高い自由度（一般的なテキストガイダンス）を使用します。優先されるパターンが存在する場合は、中程度の自由度（疑似コード/パラメータ化されたスクリプト）を使用します。操作が脆く、一貫性が重要な場合は、低い自由度（正確なスクリプト、変更なし）を使用します。狭い橋（1 つの安全な道、正確なステップを与える）対開放野原（多くの有効なルート、方向を与えてエージェントを信頼する）と考えてください。

一貫した用語を使用します。 1 つの用語を選択し、全体を通して使用します。同じスキル内で「API エンドポイント」/「URL」/「パス」または「抽出」/「プル」/「取得」/「取得」を混在させないでください。

---

2. ディレクトリ構造

skill-name/
├── SKILL.md          # 必須 — frontmatter + 指示
├── scripts/          # オプション — 実行可能コード（コンテキストに読み込まずに実行）
│   └── validate.py
├── references/       # オプション — オンデマンドで読み込まれるドキュメント
│   ├── REFERENCE.md
│   └── domain.md
└── assets/           # オプション — テンプレート、データファイル、スキーマ
    └── template.json

• ディレクトリ名は frontmatter の name フィールドと完全に一致する必要があります
• scripts/ — 自己完結型実行ファイル。エラーを明示的に処理します（「パスしない、解決します」）。スクリプトは bash 経由で実行され、その出力のみがコンテキストに入り、コードは入りません
• references/ — オンデマンドで読み込まれる追加ドキュメント。ファイルに焦点を当てます。100 行を超えるリファレンスファイルの先頭に目次を追加します
• assets/ — 静的リソース：テンプレート、設定ファイル、スキーマ、ルックアップテーブル
• Windows の場合でも、すべてのパスでフォワードスラッシュを使用します：scripts/validate.py ではなく scripts\validate.py ではなく

ドメイン組織： 複数のバリアントをサポートするスキルの場合、リファレンスに分割します：

cloud-deploy/
├── SKILL.md           # 概要 + バリアント選択
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

エージェントは関連リファレンスのみを読み込み、コンテキストを節約します。

---

3. YAML Frontmatter — 完全なフィールド リファレンス

ベース仕様フィールド (agentskills.io)

オープン標準は正確に 6 つのフィールド を定義します：

name (必須)

一意の識別子。1～64 文字。小文字の英数字とハイフンのみ。 先頭/末尾/連続したハイフンなし。XML タグなし。予約語「anthropic」または「claude」を含むことはできません。親ディレクトリ名と一致する必要があります。

ジェラン命名を優先します (動詞 + -ing)：processing-pdfs、analyzing-spreadsheets、testing-code。また許容：名詞句 (pdf-processing) または行動指向 (process-pdfs)。曖昧な名前 (helper、utils、tools) は避けてください。

name: processing-pdfs

description (必須)

自然言語の概要。1～1,024 文字。プレーンテキストのみ。XML タグなし。 これは主なトリガーメカニズムです。エージェントはこれを使用してどのスキルをロードするかを決定します。

常に三人称で書きます。 「Excel ファイルを処理します...」ではなく、「お手伝いできます...」または「このスキルを使用できます...」（視点の不一貫性は発見の問題を引き起こします）。

説明を少し「強気」にします。 Claude はスキルを過度に制御する傾向があります。スキルが何をするかと特定のトリガーコンテキストの両方を含めます。ユーザーが言うであろうキーワードをリストします。適切な場合は「明示的に X を要求しない場合でも」を追加します。

description: >-
  PDF ファイルからテキストとテーブルを抽出し、フォームを埋め、ドキュメントをマージします。
  PDF ファイルを操作する場合、またはユーザーが PDF、フォーム、またはドキュメント抽出について言及する場合に使用します。
  「PDF 処理」を明示的に要求していない場合でも使用します。

license (オプション)

SPDX 識別子またはバンドルされたファイル参照。不明な場合は省略します。

compatibility (オプション)

環境要件。1～500 文字。プレーンテキスト。スキルに実際の要件がある場合のみ含めます。ほとんどのスキルはこのフィールドが不要です。

metadata (オプション)

文字列キーと値のマップ。衝突を避けるために合理的に一意のキー名を使用します。

metadata:
  author: "your-org"
  version: "1.0"
  category: "document-processing"

allowed-tools (オプション、実験的)

スペース区切りリスト。プラットフォームがサポートする場合はスコープ付き形式を使用します。

allowed-tools: Bash(git:*) Bash(jq:*) Read Write

Claude Code 拡張フィールド

Claude Code はオープン標準を追加フィールドで拡張します。これらはプラットフォーム固有で、ベース agentskills.io 仕様の一部ではありません：

フィールド	目的
argument-hint	オートコンプリートヒント：[issue-number] または [filename] [format]
disable-model-invocation	true でオート読み込みを防止（手動 /name のみ）
user-invocable	false で / メニューから非表示（背景知識スキル）
model	このスキルがアクティブな場合のモデルオーバーライド
context	fork でフォークされたサブエージェントコンテキストで実行
agent	context: fork が設定されている場合に使用するサブエージェント型
hooks	このスキルのライフサイクルにスコープされたフック

Claude Code では、name が省略された場合はディレクトリ名にフォールバックし、description はマークダウン本体の最初のパラグラフにフォールバックします。

---

4. 本文コンテンツ

閉じる --- 後のすべてはフリーフォーム Markdown です。本文を 500 行 以下に保ちます。このリミットに近づいている場合は、詳細を references/ に移動し、明確なポインターを追加します。

推奨される構造

# [スキル名]

[1～3 文の概要]

## このスキルを使用する場合

[トリガー条件 — このスキルをアクティブにするユーザーリクエストまたはコンテキスト]

## [主要アクション] を実行する方法

[ステップバイステップの指示]

## 例

[入出力ペア]

## 一般的なエッジケース

[境界条件と処理]

## ガイドライン

[推論を含む主要原則]

段階的開示

レベル	コンテンツ	バジェット	読み込まれるタイミング
1	Frontmatter (name + description)	約 100 トークン	常に — エージェント起動時
2	SKILL.md 本体	< 500 行 / < 5K トークン	スキルがアクティブ化するとき
3	scripts/、references/、assets/	無制限	実行中のオンデマンド

レベル 3 スクリプトはコンテキストに読み込まずに実行されます — その出力のみがコンテキストウィンドウに入ります。リファレンスファイルはオンデマンドで読み取られます。これは、アクセスされるまでコンテキストペナルティなしで包括的なリソースをバンドルできることを意味します。

ファイルリファレンス

相対パスを含む標準的な Markdown リンクを使用します：

詳細な API ドキュメントについては、[リファレンスガイド](references/REFERENCE.md) を参照してください。
抽出スクリプトを実行します：`python scripts/extract.py`
TypeScript の詳細については、[TypeScript パターン](references/typescript.md) を参照してください。

リファレンスを SKILL.md から 1 階層深く に保ちます。ネストされたリファレンスチェーンを避けます — Claude は他のリファレンスファイルから参照されるファイルを部分的に読み取ることがあります。

スクリプト ガイダンス

スクリプトを参照する場合は、意図を明示的に述べます：

• 実行 (最も一般的)：「scripts/analyze.py を実行してフィールドを抽出します」
• リファレンスとして読み取る (複雑なロジックの場合)：「アルゴリズムについては scripts/analyze.py を参照してください」

スクリプトはエラーを明示的に処理する必要があります。スクリプトが失敗し、Claude がそれを理解できることを期待しないでください — フォールバックを提供し、有用なエラーメッセージを提供し、依存関係を文書化します。

MCP ツールの場合は、完全修飾リファレンスを使用します：ServerName:tool_name (例：BigQuery:bigquery_schema、GitHub:create_issue)。

---

5. ユーザーリクエストからスキルを作成

ステップ 1：意図を把握する

何かを書く前に、ユーザーが何を必要とするかを理解します：

• このスキルはエージェントに何をさせるべきですか？
• いつトリガーすべきですか？ (フレーズ、タスク、コンテキスト)
• 期待される出力形式は何ですか？
• エッジケースや制約はありますか？
• これはテストが必要ですか？ (検証可能な出力は eval から利益を得ます；執筆スタイルのような主観的な出力は多くの場合そうではありません)

会話に既にワークフロー が含まれている場合 (「これをスキルに変える」)、まず コンテキストから回答を抽出します — 使用されたツール、ステップシーケンス、ユーザーが行った修正。

ステップ 2：名前を選択する

ジェラン形式を優先します：{verb-ing}-{noun} → processing-pdfs、testing-code。 検証：小文字、ハイフンのみ、1～64 文字、先頭/末尾/連続したハイフンなし、XML タグなし、「anthropic」または「claude」を含まない名前。

ステップ 3：説明を記述する

常に三人称。アクション動詞で開始します。キーワードトリガーを含めます。「次の場合に使用...」と述べます。過度トリガーを防ぐために少し強気にします。200～400 文字を目指します。

ステップ 4：オプションフィールドを設定する

• license： ユーザー指定、または MIT/Apache-2.0、または省略
• compatibility： 実際の環境要件がある場合のみ
• metadata： 最低限 author、version、category を追加
• allowed-tools： スコープ付き形式を使用：Bash(git:*) Read
• Claude Code フィールド： 関連する場合は disable-model-invocation、argument-hint などを設定

ステップ 5：本文を記述する

ドラフトを開始します。その後、新しい目で確認して改善します。

• 1～3 文の概要
• 「このスキルを使用する場合」（トリガー条件付き）
• 「何」ではなく「なぜ」を説明するステップバイステップの指示
• 入出力の例（品質にとって重要）
• エッジケース
• 複雑なワークフローの場合：Claude が進行を確認できるコピー可能なチェックリストを提供

デフォルトアプローチと脱出ハッチを提供します。多くのオプションをリストするのではなく。「テキスト抽出には pdfplumber を使用します。OCR が必要なスキャンされた PDF には、代わりに pdf2image を使用します。」

ステップ 6：反復（評価最先）

Anthropic の推奨パターンは 2 つの Claude インスタンスを使用します：

1. ベースラインを確立 — スキルなしで代表的なタスクで Claude を実行
2. 最小限のドラフトを記述 — 観察されたギャップに対処するためのみ
3. Claude B でテスト — スキルが読み込まれた 2～3 つの現実的なプロンプトで新しいインスタンス
4. Claude B の動作を観察 — それが苦しむ場所またはミスする指示をメモ
5. Claude A に戻す — 観察したものを共有し、改善を求める
6. 満足するまで繰り返す、その後テストセットを展開

これは評価駆動開発です：広範なドキュメント作成前に eval を作成します。スキルなしでテストしてから、スキルでテストして、改善を測定します。

ステップ 7：検証

• ディレクトリ名は name フィールドと完全に一致する
• 説明：1～1,024 文字、三人称、アクション動詞、キーワードトリガー、「使用する場合...」
• name または description に XML タグがない
• すべての Markdown リンクは存在するファイルに解決
• SKILL.md 本体が 500 行以下
• 100 行を超えるリファレンスファイルに目次がある
• 利用可能な場合は skills-ref validate ./skill-directory を実行
• skills-ref to-prompt ./skill-directory を実行してエージェントが見る XML をプレビュー

---

6. 品質パターン

フェーズワークフロー

## フェーズ 1：分析

[ドメインを理解し、コンテキストを収集]

## フェーズ 2：実装

[主要なタスクを実行]

## フェーズ 3：検証

[品質をチェックし、検証を実行]

フィードバックループ

実行-検証-修正パターンは出力品質を劇的に改善します：

1. 変更を加える
2. 実行：`python scripts/validate.py`
3. 検証が失敗した場合：修正してステップ 1 に戻る
4. 検証が成功した場合のみ進める

コピー可能なチェックリスト

複雑なマルチステップタスクの場合：

このチェックリストをコピーして進捗を追跡します：

- [ ] ステップ 1：入力を分析する
- [ ] ステップ 2：計画を作成する
- [ ] ステップ 3：計画を検証する
- [ ] ステップ 4：実行する
- [ ] ステップ 5：出力を確認する

検証可能な中間出力

高リスクの操作の場合：計画 → 計画を検証 → 実行 → 確認。 計画ファイルは変更が適用される前に機械検証可能です。

決定テーブル

シナリオ	アプローチ	理由
< 100 項目	インラインアレイ	ページネーションオーバーヘッドなし
100-10K 項目	カーソルページネーション	安定した順序
> 10K 項目	キーセットページネーション	O(1) ページ取得

前後の例

**前：** `app.get('/getUser', ...)`
**後：** `app.get('/users/:id', ...)`

---

7. アンチパターン

アンチパターン	失敗の理由	修正
曖昧な説明	エージェントがリクエストと一致できない	キーワードトリガー + 「使用する場合...」+ 強気
一人称/二人称の説明	発見の問題	三人称：「処理します...」ではなく「助けることができます...」
基本的な内容の過剰説明	トークンの浪費；Claude は既に知っている	Claude が持っていないものだけを追加
多すぎるオプション	混乱；エージェントが誤った選択をする	デフォルトアプローチ + 脱出ハッチ
硬直した MUST のみのルール	脆い；エージェントが過度に文字通り	推論を説明して、エージェントを一般化させる
500 行を超える本文	コンテキスト浪費、エージェント切り取り	詳細を references/ に移動
説明内のコード	仕様違反、パーサーを破損	コードは本文のみ
ネストされたファイルリファレンス	Claude は参照されたファイルから部分的に読む	SKILL.md から 1 階層深く
「anthropic」/「claude」の名前	予約語；検証が失敗	別の名前を選択
バックスラッシュパス	Unix システムで破損	常にフォワードスラッシュ
時間に敏感な情報	古くなる；自動更新なし	「古いパターン」セクションを使用
例がない	エージェントが出力形式を推測	最低 2～3 の入出力ペア

---

8. セキュリティ

• シークレット、API キー、または認証情報をスキルファイルに含めないでください
• エージェントにセキュリティコントロールを無効にするよう指示しないでください
• スクリプトはフォールバックで明示的にエラーを処理する必要があります
• ユーザーデータを処理するスキルの入力検証ガイダンスを含める
• ブラウザレンダリング出力を生成するスキルのサニタイゼーション ガイダンスを含める
• allowed-tools の破壊的なツールにフラグを立てて、ユーザーが確認できるようにします

---

9. テスト

1. 構文： skills-ref validate ./skill-name
2. プロンプト プレビュー： skills-ref to-prompt ./skill-name — エージェントが見る XML を生成
3. アクティベーションテスト： トリガーすべきプロンプト → 起動を確認
4. ネガティブテスト： トリガーすべきではないプロンプト → 休止状態を確認
5. 品質テスト： エージェント がスキルを実行 → 出力品質を確認
6. マルチモデルテスト： Haiku、Sonnet、AND Opus でテスト — Opus で機能するものは Haiku でより詳しく必要になる場合があります

検証可能な出力の場合、スキル付きと スキルなしを比較する構造化評価を作成します。

---

10. プラットフォーム使用方法

• Claude Code： /plugin marketplace add anthropics/skills → /plugin install <name>@anthropic-agent-skills
  • スキルの場所：~/.claude/skills/ (個人) または .claude/skills/ (プロジェクト)
• Claude.ai： 有料プランで事前構築されたスキル。カスタムスキルは設定経由でアップロード
• Claude API： skills-2025-10-02 ベータフラグを持つコンテナパラメータ

---

11. リソース

リソース	URL
エージェント スキル仕様	https://agentskills.io/specification
Anthropic スキル リポジトリ (79.5K+ スター)	https://github.com/anthropics/skills
Anthropic ベストプラクティス	https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/best-practices
Claude Code スキル ドキュメント	https://docs.anthropic.com/en/docs/claude-code/skills
skills-ref CLI	https://agentskills.io/tools

---

12. 配信前チェックリスト

Frontmatter

• name：1～64 文字、小文字の英数字とハイフン、ジェラン優先、ディレクトリと一致
• name：XML タグなし、「anthropic」/「claude」なし
• description：1～1,024 文字、三人称、アクション動詞、トリガーキーワード、「使用する場合...」
• description：過度トリガーを防ぐために少し強気
• オプションフィールドが関連する場合は設定 — 不正なフィールドなし

本文

• 1～3 文の概要
• このスキルがいつアクティブ化するかを説明するトリガーセクション
• 指示は「何」ではなく「なぜ」を説明
• 最低 2～3 の入出力例
• エッジケースがカバーされている
• 500 行以下、純粋 Markdown
• 全体を通して一貫した用語

ファイル

• すべての Markdown リンクは実際のファイルに解決、1 階層深く
• 100 行を超えるリファレンスファイルに目次がある
• スクリプトはエラーメッセージで明示的にエラーを処理
• シークレットがどのファイルにもない
• すべてのパスでフォワードスラッシュ

品質

• 説明だけが関連性を決定
• 本文だけでリファレンスを読まずに実行を有効化
• 代表的なプロンプト（アクティベーション + ネガティブ + 品質）でテスト
• 実