AI Skill Builder
共有のSKILL.md形式とAnthropicの方法論を使用してエージェントスキルを構築します。すべての名前付きターゲットで動作する最小限のポータブルコアに、明示的なランタイムアダプターを追加します。ポータビリティはフォーマットスタイルではなく、テストされた互換性の主張です。
references/sources.mdはClaude Code、Codex、Qwen Codeのホストドキュメントを引用しています。他のホストはここではテストされていないため、ターゲットとするホストを確認してください（ステップ1）。
この方法論は、Markdown本文内で一貫した意味論的なXMLリージョンを意図的に要求します。これは複雑な操作指示における曖昧さを減らすための品質ポリシーであり、現在のAnthropicのプロンプトガイダンスによってサポートされ、ステップ4のフォワードテストによってチェックされます。これはポータブルエージェントスキル仕様のパーサー要件や認可境界、またはXMLだけがプロンプトインジェクションを防ぐという主張ではありません。
主要な方法論ソース: 「The Complete Guide to Building Skills for Claude」(Anthropic, 2026年1月)
- PDF: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
- 抽出テキスト:
references/ai-skill-builder-guide.md
ポータブル形式ソース: https://agentskills.io/specification
クイックスタート
スキルをゼロから作成するには、以下の4フェーズのプロセスに従ってください。
既存のスキルを改善するには、references/refining-skills.mdを読んでください。
構造を検証するには、scripts/audit-skill.shを実行してください。
呼び出し方法: ai-skill-builderを依頼してください。ホストによっては/ai-skill-builder、$ai-skill-builder、またはスキルピッカーを通じて公開される場合があります。
P0要件
この方法論で生成されるすべてのスキルは、13の要件すべてを満たします。監査やレビューではIDで引用してください。
- SKILL-REQ001-discover-target-runtimes. 作成前に、正確な製品、バージョン、呼び出しモード、インストールルート、信頼境界、ファイルシステムのセマンティクスを特定します。
- SKILL-REQ002-separate-standard-from-extensions. エージェントスキル仕様、ランタイム拡張、プロジェクト規約を別々の列に保持します。Claude、Codex、Copilot、Gemini、またはフレームワーク固有のフィールドを普遍的なものとして決して提示しないでください。
- SKILL-REQ003-use-valid-portable-core. ポータブルな
nameに一致する名前のディレクトリに必須のSKILL.mdを配置し、スキルが何をするか、いつ使用するかを示す具体的なdescriptionを含めます。標準のオプションフィールドは必要な場合のみ使用します。 - SKILL-REQ004-use-semantic-xml-regions. Markdown本文内のすべての主要な操作リージョンを、
<purpose>、<requirements>、<workflow>、<examples>、<output_contract>などの一貫した説明的なXMLタグで囲みます。それらのリージョン内にMarkdownを保持し、リテラルソースはフェンスで囲まれたコードブロックに配置します。この必須の方法論ルールは最高品質の指示分離を目指していますが、エージェントスキルパーサーの要件やセキュリティ境界ではありません。scripts/audit-skill.shは、リージョンがない本文、アンバランスまたはネストが間違ったタグ、またはすべてのリージョン外にある##見出しで失敗します。 - SKILL-REQ005-design-progressive-disclosure. アクティベーションの説明を正確にし、メインワークフローを簡潔に保ちます。真に条件付きの詳細は、焦点を絞った直接リンクされた参照に移動します。再利用可能な自動化はスクリプトに、出力マテリアルはアセットに保持します。
- SKILL-REQ006-preserve-operational-context. すべての参照またはスクリプトは、いつ使用するか、どのような入力を受け付けるか、何を返すか変更するか、失敗がどのように報告されるかを示さなければなりません。深い参照連鎖は避けてください。
- SKILL-REQ007-make-invocation-correct. 自動アクティベーションと明示的な呼び出しをテストします。ランタイムがパラメータをサポートする場合は、空、位置指定、名前付き、引用符付き、Unicode、無効、大きな入力をテストします。別のランタイムが同じ置換構文を実装していると想定しないでください。
- SKILL-REQ008-minimize-tool-authority. スキルとバンドルされたスクリプトを実行可能な依存関係として扱います。必要な最小限の権限を要求し、入力を検証し、可能な場合は承認プロンプトを保持し、プロンプト区切り文字をプロンプトインジェクション防止として決して説明しないでください。
- SKILL-REQ009-validate-every-harness. 各サポート対象ハーネスで、発見、読み込み、参照、スクリプト、引数、シンボリックリンク、重複解決、更新、削除を検証します。1つのパーサーを通過しても、クロスランタイム互換性は証明されません。
- SKILL-REQ010-preserve-user-state. インストールとアンインストールは、正確な生成パスを所有し、手動編集を保持し、複数の設定済みスキルルートをサポートし、インストーラーが所有するリンクまたはファイルのみを削除する必要があります。
- SKILL-REQ011-measure-context-and-runtime-cost. 発見メタデータサイズ、読み込まれた指示サイズ、条件付き参照コスト、スクリプトの時間/メモリ/I/O、重複読み込みを記録します。ターゲットランタイムがそれらを規範的にしない限り、行とトークンのターゲットはヒューリスティックとして扱います。
- SKILL-REQ012-forward-test-real-tasks. 現実的なポジティブ、ネガティブ、曖昧、敵対的なプロンプトを使用します。スキルがリストに表示されたかどうかではなく、タスクの結果を確認します。
- SKILL-REQ013-separate-authoring-from-execution. タスクがスキルの変更、スキルを使用して成果物や結果を生成すること、または証拠からスキルを評価することのいずれであるかを分類します。明示的な作成決定が受け入れ、一般化しない限り、ランタイム入力、生成された出力、例、ドッグフードの観察はスキル指示になりません。
リージョン名は、1つの普遍的な分類法ではなくタスクに従います。ワークフローは<workflow>、参照スキルは<decision_guide>、マルチモードスキルは<routing>、厳密な結果契約は<output_contract>、インライン参照マテリアルは<reference>、バンドルされたファイルとソースへのポインタは<resources>を使用します。タグは一貫性があり、説明的で、バランスが取れており、タスクが必要とする以上に深くネストされてはなりません。標準対拡張のマトリックス、クレーム監査、ホストごとの検証レシートはreferences/portability-and-claim-audit.mdにあります。
しくみ
Anthropicガイドからの4フェーズ方法論。各フェーズには完了定義があります。次のフェーズを開始する前に満たさなければならない条件です。
| フェーズ | アクティビティ | 完了定義 |
|---|---|---|
| 1: 計画と設計 | ターゲットホスト、ユースケース、カテゴリ、成功基準を定義 | 基準が測定可能で、カテゴリが選択されている |
| 2: 実装 | フォルダを作成、SKILL.mdを記述、リソースを追加 | audit-skill.shが失敗を報告しない |
| 3: テスト | トリガー、機能、パフォーマンス、互換性、フォワードテスト | すべての名前付きホストが検証レシートで合格、ベースラインが記録されている |
| 4: 配布 | パッケージ化、文書化、公開 | クリーンなルートからインストールが確認されている |
フェーズ1は以下のステップ1〜2をカバーし、フェーズ2〜4はステップ3〜5に対応します。
各フェーズの所要時間は誰がまたは何が実行するかに依存するため、このスキルは実時間の見積もりを述べず、あなたが構築するスキルも述べるべきではありません。
スキル作成ワークフロー
ステップ1: 要件の発見
最初にドメインを調査 — 指示を書く前に、ホストのWebツールを使用して現在のベストプラクティスを確認してください。古いガイダンスはないより悪いです。エージェントはそれを自信を持って実行します。
すべてのソースを保持: 確認した内容のメモとともに、参照したすべてのURLを記録します。ソースのないガイダンスは検証または更新できません。
調査戦略、ソース品質基準、必要なソースセクション形式については: references/research.md
- リクエストを分類: 作成（スキルの変更）、実行（スキルを使用して結果を生成）、または評価（証拠からスキルを判断）。タスクコンテンツを設計入力として使用する前に、成果物と変更境界に名前を付けます（SKILL-REQ013）。
- 問題とターゲットユーザーを特定
- すべてのターゲットホストとバージョン、その発見ルート、呼び出し形式、リロード動作を特定。不明なものは推測せずに不明としてマーク。並行パッケージを作成する前に、既存のスキルルートとプロジェクトガイダンスを調査。
- 2〜3の具体的なユースケースを定義
- 測定可能な成功基準を設定（節約された時間、削減されたエラー、改善された品質）
- スキルカテゴリを選択:
| カテゴリ | 入力 → 出力 | 例 |
|---|---|---|
| 1: ドキュメントとアセット作成 | データ/仕様 → ドキュメント、コード、レポート | APIテスト生成、ミーティングノート要約 |
| 2: ワークフロー自動化 | タスクパラメータ → 完了したマルチステッププロセス | デプロイパイプライン、コードレビューワークフロー |
| 3: MCP拡張 | MCPツール出力 → よりスマートなオーケストレーション | スマートファイル検索、BigQueryアシスタント |
詳細なカテゴリガイダンス: references/categories.md
インタラクティブな発見質問: references/discovery.md
ステップ2: 構造の設計
プログレッシブディスクロージャーを使用して設計 — 3つの読み込みレベル:
| レベル | 読み込み時 | 目標の長さ | 内容 |
|---|---|---|---|
| 1: メタデータ | 常時（約100語） | name + description | トリガー条件 |
| 2: SKILL.md本文 | スキルがトリガーされた時 | 5,000語未満（理想的には2,000語未満） | コアワークフロー + ポインタ |
| 3: references/ ファイル | 必要に応じて | 無制限 | 詳細、スキーマ、例 |
プログレッシブディスクロージャーの作成のヒントと成功指標については: references/best-practices.md
ステップ3: 実装
重要なルール:
- ✅ ファイル名は
SKILL.mdでなければならない（README.mdではない） - ✅ フォルダ名はkebab-caseでなければならない — スペースなし、大文字なし (
my-skillでありMy Skillではない) - ✅ YAMLフロントマターには
nameとdescriptionを含めなければならない。バージョンはmetadataの下に配置 - ✅ 説明には特定のトリガーフレーズを含めなければならない — ユーザーがスキルをアクティベートするために言う内容
- ✅ 説明は1024文字未満でなければならない（厳しい制限 — 長い説明は切り捨てられる）
- ✅ フロントマターフィールドにXMLの山括弧（
<または>)は不可 — Anthropicのスキルガイドからのホスト制限であり、YAMLルールではない。本文には影響しない - ✅ 本文: すべての主要セクションはバランスの取れた説明的なXMLリージョン内に配置され、各行に固有のタグ（
<purpose>、<requirements>、<workflow>、<examples>、<output_contract>）を持ち、内部はMarkdown、リテラルソースはフェンスで囲まれたコードブロック（SKILL-REQ004）。H1タイトルは外側にあってもよい - ❌ スキルフォルダ内にREADME.mdは不可 — すべてのドキュメントはSKILL.mdまたはreferences/に配置（例外: スキルフォルダ外のGitHubリポジトリルートにあるREADME.mdはGitHub用として許容）
- ❌ フォルダ名にスペースやアンダースコアは不可 (
my_skill→my-skill)
フロントマター: 必須フィールド:
---
name: your-skill-name # kebab-caseのみ。スペース、大文字、アンダースコアは不可
description: What it does. Use when user asks to "specific phrase", "another phrase".
# 含めるもの: 何をするか + いつ使用するか（トリガー条件）
# 1024文字未満。XMLの山括弧は不可。
# "claude" や "anthropic" で始めない（予約済み名前空間）。
---
すべてのオプションフィールド（license、compatibility、allowed-tools、metadata）とホストポータビリティに関する注意: references/best-practices.md
ポジショニング言語（「テストを87%高速に生成」）はリポジトリのREADMEに属し、descriptionには決して入れないでください。references/best-practices.mdを参照。
フォルダ構造（注釈付きClaude Codeスタンドアロン例: references/best-practices.md、セクション「Folder Structure Patterns」）:
| ディレクトリ | コンテキストに読み込む？ | 使用目的 |
|---|---|---|
references/ | はい、必要に応じて | スキーマ、APIドキュメント、ポリシー、ワークフローガイド |
references/examples/ | 必要に応じて | ユーザーがコピーして適応する実用的なコード |
scripts/ | いいえ（直接実行） | バリデーター、スキャフォルダー、ユーティリティ |
assets/ | いいえ（出力で使用） | 画像、フォント、HTMLテンプレート（スキルが出力に貼り付ける） |
注意: プラグインスキル（plugin-name/skills/内）はexamples/をトップレベルに配置できます — それはプラグイン開発の慣習です。スタンドアロンな~/.claude/skills/スキルの場合、例はreferences/内に配置してください。
新しいスキルをスキャフォールドするには: bash scripts/scaffold-skill.sh my-skill-name
（別のホストのルートをターゲットにするにはSKILLS_DIRを設定）
テンプレートから開始するには: references/examples/SKILL-template.mdをコピー
ステップ4: テスト
5つのテストアプローチ（順に実行）:
- トリガーテスト — エージェントが期待されるフレーズでアクティベートされ、無関係なリクエストではアクティベートされないことを確認
- 機能テスト — スキルのコアワークフローが既知の入力に対して正しい出力を生成することを検証
- パフォーマンステスト — ベースラインからの改善を測定（節約された時間、エラー削減、一貫性）
- 互換性テスト — すべての名前付きホストとバージョンで、発見、明示的な呼び出し、参照の読み込み、スクリプト実行、重複/名前解決を検証。各ホストでクリーンなセッションを開始し、ホスト独自のバリデーターが存在する場合はそれを実行（Codexには
skill-creator/scripts/quick_validate.pyが同梱）、インストーラーの再実行、複数のルート、シンボリックリンクターゲット、変更されたユーザーファイル、アンインストールをテストし、ホストごとの検証レシートを記録（references/portability-and-claim-audit.md） - フォワードテスト — 現実的なポジティブ、ネガティブ、曖昧、敵対的なプロンプト。スキルがリストに表示されたかどうかではなく、タスクの結果を判断し、近くのタスクに過剰にトリガーされないことを確認（SKILL-REQ012）
トリガー問題のデバッグ:
エージェントに尋ねる: 「[スキル名] スキルをいつ使用しますか？」
エージェントはその説明を引用して返すはずです。不足または曖昧な部分に基づいて調整します。
アンダートリガーの修正: より具体的なトリガーフレーズと関連する技術用語を追加します。
オーバートリガーの修正: 説明にネガティブトリガーを追加します:
description: 契約レビューのためにPDF法務文書を処理します。「この契約をレビュー」「法的文書を分析」「契約条項を抽出」に使用。一般的なPDF表示、画像抽出、または非法律文書には使用しないでください（代わりにdoc-converterスキルを使用）。
4つの障害モードすべてをカバーする完全な診断と修正ガイドについては: references/troubleshooting.md
構造を検証するには:
bash scripts/audit-skill.sh /path/to/YOUR-SKILL
references/troubleshooting.mdには、audit-skill.shが失敗を報告する問題の診断と修正に関する詳細なガイダンスが含まれています。