ソースの出典

公式リポジトリ: anthropics/skills — mcp-builder/SKILL.md
追加のスキルエンジニアリングリファレンス:

パート1: Anthropic公式 `mcp-builder/SKILL.md`（3段階プログレッシブディスクロージャーの模範）

概要

MCP（Model Context Protocol）サーバーを作成し、LLMが適切に設計されたツールを通じて外部サービスとやり取りできるようにします。MCPサーバーの品質は、LLMが現実世界のタスクをどれだけ効果的に実行できるかによって測られます。

プロセス

🚀 高レベルのワークフロー

高品質なMCPサーバーの作成には、主に4つのフェーズがあります。

フェーズ1: 徹底的な調査と計画

1.1 現代的なMCP設計を理解する

APIカバレッジ vs ワークフローツール: 包括的なAPIエンドポイントカバレッジと、特化したワークフローツールのバランスを取ります。ワークフローツールは特定のタスクに便利ですが、包括的なカバレッジによりエージェントは柔軟に操作を組み合わせることができます。パフォーマンスはクライアントによって異なります。基本的なツールを組み合わせるコード実行が有効なクライアントもいれば、より高レベルのワークフローの方が効果的なクライアントもいます。迷った場合は、包括的なAPIカバレッジを優先してください。

ツールの命名と発見可能性: 明確で説明的なツール名は、エージェントが適切なツールを素早く見つけるのに役立ちます。一貫性のあるプレフィックス（例: github_create_issue、github_list_repos）とアクション指向の命名を使用します。

コンテキスト管理: エージェントは簡潔なツール説明と、結果をフィルタリング/ページネーションできる機能の恩恵を受けます。焦点を絞った関連性の高いデータを返すツールを設計します。一部のクライアントはコード実行をサポートしており、エージェントがデータを効率的にフィルタリングおよび処理するのに役立ちます。

実用的なエラーメッセージ: エラーメッセージはエージェントを解決策に導き、具体的な提案と次のステップを提供する必要があります。

1.2 MCPプロトコルドキュメントを学習する

MCP仕様をナビゲートする: サイトマップから関連ページを見つけます: https://modelcontextprotocol.io/sitemap.xml 次に、.md サフィックスを付けて特定のページをマークダウン形式で取得します（例: https://modelcontextprotocol.io/specification/draft.md）。

確認すべき主要なページ:

仕様の概要とアーキテクチャ
トランスポートメカニズム（ストリーミング可能HTTP、stdio）
ツール、リソース、プロンプトの定義

1.3 フレームワークドキュメントを学習する

推奨スタック:

言語: TypeScript（高品質なSDKサポートと、多くの実行環境（例: MCPB）での優れた互換性。さらに、AIモデルはTypeScriptコードの生成が得意で、その幅広い使用、静的型付け、優れたリンティングツールの恩恵を受けられます）
トランスポート: リモートサーバーにはストリーミング可能HTTP（ステートフルなセッションやストリーミング応答とは対照的に、ステートレスなJSONを使用するため、スケールとメンテナンスが容易）。ローカルサーバーにはstdio。

フレームワークドキュメントを読み込む:

MCPベストプラクティス: 📋 ベストプラクティスを表示 - すべてのMCPサーバー向けのコアガイドライン
TypeScript（推奨）: ⚡ TypeScriptガイド - TypeScriptのパターンと例
Python向け: 🐍 Pythonガイド - Python/FastMCPのパターンと例

1.4 実装を計画する

APIを理解する: サービスのAPIドキュメントを確認し、主要なエンドポイント、認証要件、データモデルを特定します。必要に応じてウェブ検索とウェブフェッチを使用します。

ツールの選択: 包括的なAPIカバレッジを優先します。最も一般的な操作から始めて、実装するエンドポイントをリストアップします。

フェーズ2: 実装

2.1 プロジェクト構造を設定する

プロジェクトのセットアップについては、言語別ガイドを参照してください:

⚡ TypeScriptガイド - プロジェクト構造、package.json、tsconfig.json
🐍 Pythonガイド - モジュール構成、依存関係

2.2 コアインフラストラクチャを実装する

共有ユーティリティを作成:

認証付きAPIクライアント
エラーハンドリングヘルパー
レスポンスフォーマット（JSONとMarkdown）
ページネーションサポート

2.3 ツールを実装する

各ツールについて:

入力スキーマ:

TypeScriptではZod、PythonではPydanticを使用
制約と明確な説明を含める
フィールド説明に例を追加

出力スキーマ:

可能な場合は構造化データのために outputSchema を定義
ツール応答で structuredContent を使用（TypeScript SDKの機能）
クライアントがツール出力を理解して処理するのに役立つ

ツールの説明:

機能の簡潔な要約
パラメータの説明
戻り値のスキーマ

実装:

I/O操作には非同期/待機（async/await）
実用的なメッセージによる適切なエラーハンドリング
該当する場合はページネーションをサポート
最新のSDKを使用する場合は、テキストコンテンツと構造化データの両方を返す

注釈:

readOnlyHint: true/false
destructiveHint: true/false
idempotentHint: true/false
openWorldHint: true/false

フェーズ3: レビューとテスト

3.1 コード品質

以下の点を確認:

重複コードなし（DRY原則）
一貫性のあるエラーハンドリング
完全な型カバレッジ
明確なツール説明

3.2 ビルドとテスト

TypeScript:

npm run build を実行してコンパイルを確認
MCPインスペクターでテスト: npx @modelcontextprotocol/inspector

Python:

構文確認: python -m py_compile your_server.py
MCPインスペクターでテスト

詳細なテストアプローチと品質チェックリストについては、言語別ガイドを参照してください。

フェーズ4: 評価を作成する

MCPサーバーを実装した後、その効果をテストするための包括的な評価を作成します。

完全な評価ガイドラインについては、✅ 評価ガイドを読み込んでください。

4.1 評価の目的を理解する

評価を使用して、LLMがMCPサーバーを効果的に使用して現実的で複雑な質問に答えられるかどうかをテストします。

4.2 10個の評価質問を作成する

効果的な評価を作成するには、評価ガイドに記載されているプロセスに従います:

ツールの検査: 利用可能なツールをリストアップし、その機能を理解する
コンテンツの探索: 読み取り専用（READ-ONLY）操作を使用して利用可能なデータを探索する
質問の生成: 10個の複雑で現実的な質問を作成する
回答の検証: 各質問を自分で解いて回答を検証する

4.3 評価要件

各質問が以下を満たしていることを確認:

独立: 他の質問に依存していない
読み取り専用: 非破壊的な操作のみが必要
複雑: 複数のツール呼び出しと深い探索が必要
現実的: 人間が気にする実際のユースケースに基づく
検証可能: 文字列比較で検証できる単一の明確な回答
安定: 回答が時間とともに変わらない

4.4 出力形式

以下の構造でXMLファイルを作成:

<evaluation>
  <qa_pair>
    <question>動物コードネームを持つAIモデルローンチに関する議論を見つけてください。あるモデルにはASL-X形式の特定の安全指定が必要でした。斑点のある野生のネコ科の動物にちなんで名付けられたモデルに対して決定されていた数字Xは何ですか?</question>
    <answer>3</answer>
  </qa_pair>
<!-- さらにqa_pairを追加... -->
</evaluation>

リファレンスファイル

📚 ドキュメントライブラリ

開発中に必要に応じてこれらのリソースを読み込んでください:

コアMCPドキュメント（最初に読み込む）

MCPプロトコル: サイトマップ https://modelcontextprotocol.io/sitemap.xml から始め、.md サフィックスを付けて特定のページを取得
📋 MCPベストプラクティス - 汎用的なMCPガイドライン。以下を含む:
- サーバーとツールの命名規則
- レスポンス形式ガイドライン（JSON vs Markdown）
- ページネーションのベストプラクティス
- トランスポートの選択（ストリーミング可能HTTP vs stdio）
- セキュリティとエラーハンドリングの標準

SDKドキュメント（フェーズ1/2で読み込む）

Python SDK: https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md から取得
TypeScript SDK: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md から取得

言語別実装ガイド（フェーズ2で読み込む）

評価ガイド（フェーズ4で読み込む）

✅ 評価ガイド

パート2: Claude Code動的コンテキストインジェクション (`!`command``) スキルの模範

ソース: Claude Codeスキルドキュメント

---
name: pr-summary
description: プルリクエストの変更を要約します。ユーザーが現在のPRまたはブランチ差分のレビュー、要約、監査を依頼したときに使用します。
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## プルリクエストコンテキスト
- PR差分: !`gh pr diff`
- PRコメント: !`gh pr view --comments`
- 変更されたファイル: !`gh pr diff --name-only`

## あなたのタスク
このプルリクエストを、具体的なファイルレベルのリスク、破壊的変更、検証手順とともに要約してください...

パート3: OpenAI Codex / ChatGPT `agents/openai.yaml` サイドカースキーマ

ソース: OpenAIスキル構築ドキュメント

interface:
  display_name: "自己進化型メタプロンプト＆ロールアーキテクト"
  short_description: "ツール間でプロンプト、スキル、エージェントロールをコンパイル、評価、適応させます"
  icon_small: "./assets/icon-small.svg"
  icon_large: "./assets/icon-large.png"
  brand_color: "#2563EB"
  default_prompt: "評価スコアカードを使用して、プロンプト、スキル、またはエージェントロール定義を設計または最適化します。"

policy:
  allow_implicit_invocation: true

dependencies:
  tools:
    - type: "mcp"
      value: "git"
      description: "リポジトリ検査のためのGit MCPサーバー"

パート4: エージェントスキルPEP 723自己完結型スクリプトハーネスの模範

ソース: エージェントスキル — スクリプトの使用 (agentskills.io)

# /// script
# dependencies = [
#   "pydantic>=2.0",
# ]
# requires-python = ">=3.10"
# ///
"""エージェントスキル呼び出しのために `uv run` を介して設計された、自己完結型の非対話型CLIスクリプト。"""

import argparse
import json
import sys


def main() -> int:
    parser = argparse.ArgumentParser(
        description="対話型プロンプトなしでスキルまたはロールのフロントマターとトークンバジェットを検証します。"
    )
    parser.add_argument("--input", required=True, help="対象のMarkdownファイルへのパス")
    parser.add_argument("--max-chars", type=int, default=12000, help="文字バジェットの上限")
    parser.add_argument("--dry-run", action="store_true", help="書き込みせずにチェックをプレビュー")
    args = parser.parse_args()

    try:
        with open(args.input, "r", encoding="utf-8") as f:
            text = f.read()
    except FileNotFoundError:
        sys.stderr.write(
            f"エラー: ファイル '{args.input}' が見つかりません。--input <path> で有効なパスを指定してください。\n"
        )
        return 1

    char_count = len(text)
    passed = char_count <= args.max_chars
    result = {
        "file": args.input,
        "char_count": char_count,
        "max_chars": args.max_chars,
        "passed": passed,
        "remediation": None if passed else f"{char_count - args.max_chars}文字削除するか、詳細をreferences/に移動してください。",
    }
    sys.stdout.write(json.dumps(result, ensure_ascii=False, indent=2) + "\n")
    return 0 if passed else 2


if __name__ == "__main__":
    sys.exit(main())

お気に入りのAIに質問する

ドキュメント

ソースの出典

パート1: Anthropic公式 mcp-builder/SKILL.md（3段階プログレッシブディスクロージャーの模範）

概要

プロセス

🚀 高レベルのワークフロー

フェーズ1: 徹底的な調査と計画

1.1 現代的なMCP設計を理解する

1.2 MCPプロトコルドキュメントを学習する

1.3 フレームワークドキュメントを学習する

1.4 実装を計画する

フェーズ2: 実装

2.1 プロジェクト構造を設定する

2.2 コアインフラストラクチャを実装する

2.3 ツールを実装する

フェーズ3: レビューとテスト

3.1 コード品質

3.2 ビルドとテスト

フェーズ4: 評価を作成する

4.1 評価の目的を理解する

4.2 10個の評価質問を作成する

4.3 評価要件

4.4 出力形式

リファレンスファイル

📚 ドキュメントライブラリ

コアMCPドキュメント（最初に読み込む）

SDKドキュメント（フェーズ1/2で読み込む）

言語別実装ガイド（フェーズ2で読み込む）

評価ガイド（フェーズ4で読み込む）

パート2: Claude Code動的コンテキストインジェクション (!command``) スキルの模範

パート3: OpenAI Codex / ChatGPT agents/openai.yaml サイドカースキーマ

パート4: エージェントスキルPEP 723自己完結型スクリプトハーネスの模範

Individual skills in this repo

DataShrimp/skills

DataShrimp/skills

DataShrimp/skills

関連スキル

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

パート1: Anthropic公式 `mcp-builder/SKILL.md`（3段階プログレッシブディスクロージャーの模範）

パート2: Claude Code動的コンテキストインジェクション (`!`command``) スキルの模範

パート3: OpenAI Codex / ChatGPT `agents/openai.yaml` サイドカースキーマ