create-seed-skill

シードスキルを作成する

インテグレーション型スキルをゼロからスキャフォールディングします。シードスキルは、SKILL.md、参照アセット、そしてエージェントが動作しテスト可能なインテグレーションを作り上げるための知識を提供する prompts.jsonl エントリーで構成されます。

こんな場合に使用します

インテグレーションスキル（このスキルを使用します）：

• コード生成と実際の API テストを伴う SDK またはフレームワークのラッパーを作成する
• 評価で確認するのは、「エージェントが実際の API を呼び出すコードを作成し、テストに合格したか」
• 例：ydc-ai-sdk-integration、teams-anthropic-integration

ツールスキル（このスキルは使用しないでください）：

• エージェントがコードを書くのではなくコマンドを実行する CLI ラッパー
• テストディレクトリや生成ファイルがない
• 例：youdotcom-cli

判断ポイント

まず開発者に確認してください：

これはインテグレーションスキル（エージェントがコードとテストを生成する）ですか、それともツールスキル（エージェントが CLI コマンドを実行する）ですか？

• インテグレーション → このワークフローを続けます
• ツール → 停止します。このスキルはツールスキルには不要です。

---

ワークフロー

ステップ 1 — 情報を収集する

以下の質問をすべて一度に尋ねてください（1つずつ尋ねないでください）。

1. スキル名：何という名前にしますか？（小文字、ハイフン区切り。例：my-sdk-integration）
2. パッケージ：ラップする npm/pip パッケージは何ですか？正確なパッケージ名を含めてください。
3. 言語：TypeScript、Python、それとも両方ですか？
   • 両方の場合：言語ごとに別々のアセットファイル、prompts.jsonl エントリーが2つ（-typescript と -python が1つずつ）、さらに tests/<skill-name>-typescript/ と tests/<skill-name>-python/ の tests/ ディレクトリが2つ必要です。それぞれに .gitkeep ファイルを配置してください。
   • 1言語の場合：アセット一式が1つ、prompts.jsonl エントリーが1つ、.gitkeep ファイルを含む tests/<skill-name>/ ディレクトリが1つ必要です。
4. パス A（基本）：最もシンプルに動作するインテグレーションは何ですか？1つの関数、1回の API 呼び出しなど。
5. パス B（拡張）：自然な拡張は何ですか？MCP、ストリーミング、ツールのフィルタリングなど。
6. 必須の環境変数：どの API キーが必要ですか？（例：MY_API_KEY、OPENAI_API_KEY）
7. テストクエリ：インテグレーションが回答できるべき、複数のキーワードを含む決定的な答えが得られる事実に関する質問は何ですか？（テストクエリの選び方を参照）

ステップ 2 — 参照アセットを読む

コードを書く前に、必要な構成を理解するため、参照アセットを読んでください。

• assets/example-SKILL.md — SKILL.md の完全なテンプレート
• assets/example-path-a.ts — TypeScript のパス A アセット構成
• assets/example-test.spec.ts — TypeScript テストアセット構成
• assets/example-pyproject.toml — Python プロジェクト設定アセット
• assets/example-test_integration.py — Python テストアセット構成

ステップ 3 — ファイルを作成する

すべてのファイルを一度に作成します。スキルは skills/<skill-name>/ に配置します。

ディレクトリ構成：

skills/<skill-name>/
├── SKILL.md
└── assets/
    # TypeScript:
    ├── path-a-<variant>.ts       # Path A integration
    ├── path-b-<variant>.ts       # Path B integration (if applicable)
    ├── integration.spec.ts       # Bun test file
    # Python:
    ├── path_a_<variant>.py       # Path A integration
    ├── path_b_<variant>.py       # Path B integration (if applicable)
    ├── test_integration.py       # pytest file
    └── pyproject.toml            # Python project config (required for uv run pytest)

# Also create (see below):
tests/<skill-name>/               # single language
└── .gitkeep
# — or for both languages —
tests/<skill-name>-typescript/
└── .gitkeep
tests/<skill-name>-python/
└── .gitkeep

さらに、エージェントが書き込みを始める前に git 上でディレクトリが存在するよう、.gitkeep ファイルを含む tests/ の評価対象ディレクトリを作成してください。

• 1言語の場合：tests/<skill-name>/.gitkeep
• 両言語の場合：tests/<skill-name>-typescript/.gitkeep と tests/<skill-name>-python/.gitkeep

# Single language (adjust path as needed):
mkdir -p tests/<skill-name> && touch tests/<skill-name>/.gitkeep

# Both languages:
mkdir -p tests/<skill-name>-typescript tests/<skill-name>-python
touch tests/<skill-name>-typescript/.gitkeep tests/<skill-name>-python/.gitkeep

ステップ 4 — prompts.jsonl エントリーを追加する

data/prompts/prompts.jsonl に、言語ごとに1つエントリーを追記します。

1言語の場合のテンプレート（具体例を1つ選んでください。TypeScript や Python をプレースホルダーのまま残さないでください）：

TypeScript：

{"id":"<skill-name>","input":["Using the <skill-name> skill, create a working TypeScript <description of Path A> integration. Write flat minimal code with no comments or TSDoc. Write integration tests that call real APIs and assert on meaningful response content. Save everything to the tests/<skill-name> directory.","Extend the integration with <description of Path B>. Write flat minimal code with no comments or TSDoc. Update the integration tests to verify the extended integration also works with a live query."],"metadata":{"cwd":"tests/<skill-name>","language":"typescript"}}

Python：

{"id":"<skill-name>","input":["Using the <skill-name> skill, create a working Python <description of Path A> integration. Write flat minimal code with no comments or docstrings. Write integration tests that call real APIs and assert on meaningful response content. Save everything to the tests/<skill-name> directory.","Extend the integration with <description of Path B>. Write flat minimal code with no comments or docstrings. Update the integration tests to verify the extended integration also works with a live query."],"metadata":{"cwd":"tests/<skill-name>","language":"python"}}

両言語の場合 — エントリーを2つ追記します：

{"id":"<skill-name>-typescript","input":["Using the <skill-name> skill, create a working TypeScript <description of Path A> integration. Write flat minimal code with no comments or TSDoc. Write integration tests that call real APIs and assert on meaningful response content. Save everything to the tests/<skill-name>-typescript directory.","Extend the integration with <description of Path B>. Write flat minimal code with no comments or TSDoc. Update the integration tests to verify the extended integration also works with a live query."],"metadata":{"cwd":"tests/<skill-name>-typescript","language":"typescript"}}
{"id":"<skill-name>-python","input":["Using the <skill-name> skill, create a working Python <description of Path A> integration. Write flat minimal code with no comments or docstrings. Write integration tests that call real APIs and assert on meaningful response content. Save everything to the tests/<skill-name>-python directory.","Extend the integration with <description of Path B>. Write flat minimal code with no comments or docstrings. Update the integration tests to verify the extended integration also works with a live query."],"metadata":{"cwd":"tests/<skill-name>-python","language":"python"}}

プロンプトのルール：

• 各エントリーは、ターンがちょうど2つであること
• エージェントが推測しないよう、ターン 1 で言語を明示すること（「TypeScript」または「Python」）
• 成果のみを説明し、クラス名、メソッド名、設定キーには決して触れないこと
• ターン 1：基本的なインテグレーションとテスト
• ターン 2：拡張とテストの更新
• metadata.cwd はステップ 3 で作成した tests/ ディレクトリと一致させること（評価ツールはここからファイルを読み込みます）
• metadata.language は typescript または python にすること

ステップ 5 — シンボリックリンクを作成

ln -s ../../skills/<skill-name> .claude/skills/<skill-name>

ステップ 6 — 検証

bunx @plaited/development-skills validate-skill skills/<skill-name>

---

優れたシードスキルの条件

SKILL.md に含める内容

1. 正しいフロントマター — name、description、license、compatibility、allowed-tools、assets リスト、metadata
2. 判断ポイント — パス A とパス B の簡潔な説明と、明確な質問を 1 つ
3. インストール手順 — 正確なパッケージ名とインストールコマンド
4. 完全なコードテンプレート — 擬似コードではなく、動作する完全な例
5. セキュリティセクション — インテグレーションが信頼できないウェブコンテンツを取得する場合は、プロンプトインジェクションに関する警告を含めます（W011）
6. インテグレーションテストの生成セクション — すべてのアセットファイルへの Markdown リンクと明示的なルール

インテグレーションテスト生成ルール（以下をすべて含める）

**Rules:**
- No mocks — call real APIs
- Assert on keywords from a deterministic query, not just `length > 0`
- Validate required env vars at test start (inside the test function, not at module scope)
- TypeScript: use `bun:test`, dynamic imports inside tests, `timeout: 60_000`
- Python: use `pytest`, import inside test function; always include `pyproject.toml` with `pytest` in `[dependency-groups] dev`
- Run TypeScript tests: `bun test` | Run Python tests: `uv run pytest`

リファレンスアセットに求められる条件

• コンパイルして実行できること — 擬似コードやプレースホルダーを含めない
• エージェントの instructions／system_prompt にセキュリティ指示を含める
• インテグレーションファイル（__main__ の例として）とテストのアサーションの両方で、ステップ 1 のテストクエリを使用する
• キーワードをアサートすること — length > 0 だけでは不十分
• TypeScript：呼び出し可能な関数をエクスポートし、テストで動的な import() を使用する
• Python：main(query: str) -> str 関数を定義し、テスト関数内でインポートを遅延させる

---

テストクエリの選び方

本当の目的：LLM が答えを知っているかではなく、インテグレーションコードが実行されたことを確認することです。

多くの LLM は、ツールを呼び出さなくても記憶から事実に関する質問に答えられます。検索しなくてもモデルが答えられるクエリでは、MCP サーバーまたは SDK ツールが呼び出されたことを証明できません。インテグレーションがツールを暗黙にスキップしても、テストに合格する可能性があります。

実際に重要なこと： テストは、コードパスが正常に動作した場合にのみ合格します。つまり、SDK が初期化され、MCP サーバーに到達し、応答が返された場合です。典型的なツール出力と一致するキーワードアサーションは、アサーションがないよりは適切ですが、ツールが呼び出されたことの証明にはなりません。

実践的な指針：

• ツールを使うよう明示的に指示する文をクエリの先頭に付ける — モデルの判断に任せず、ツールを確実に呼び出させます
• length > 0 だけでなく、内容をアサートできるよう、安定した複数のキーワードを含む答えが得られるクエリを使います
• LLM-as-judge グレーダー（scripts/grader.ts）は、キーワードが含まれているかどうかだけでなく、生成されたコードの構造も評価します

良い例（明示的なツール指示＋安定したキーワード）：

• "Search the web for the three branches of the US government" → legislative、executive、judicial をアサートします
• "Use web search to find what programming language TypeScript compiles to" → javascript をアサートします
• "Search the web for the four classical elements" → earth、water、fire、air をアサートします

"Search the web for..." または "Use [tool name] to find..." という接頭辞は、推測ではなく、ツールの使用を明示的に指示します。プロンプトに従うには、モデルはツールを呼び出す必要があります。

避けるもの：

• 事実を尋ねるだけのクエリ（「3 つの部門は何ですか……」） — モデルが記憶から回答し、ツールを完全にスキップする可能性があります
• 「AI の最新ニュースは何ですか？」 — 毎日変化するため、予測可能なキーワードがありません
• 「一文でこんにちはと言ってください。」 — 意味のある内容をアサートできません

評価グレーダーの注意事項

グレーダー（scripts/grader.ts）は metadata.cwd から実行されます。

• TypeScript：bun test を実行し、生成されたファイルを対象に **/*.{ts,js} をスキャンします
• Python：uv run pytest を実行します（テストディレクトリに pyproject.toml が必要です）
• テスト出力と生成されたファイルの内容を Haiku に送信し、LLM による判定で採点します（0.0～1.0）
• 合格のしきい値は約 0.65 です。目標は 0.95 です

SKILL.md で防ぐべき一般的な失敗例：

• pytest がない：開発用依存関係に pytest を含む pyproject.toml アセットを必ず含めてください
• モジュールスコープでの環境変数チェック：テスト収集エラーを避けるため、Python のインポートはテスト関数内に記述してください
• 指示が具体的すぎるプロンプト：prompts.jsonl には実装手順ではなく、達成すべき結果を記述してください
• ツールのイントロスペクション：SDK のイベントストリームやツール呼び出しオブジェクトに対するアサーションをエージェントに指示しないでください
• 自由回答形式のテストクエリ：「最新の AI ニュース」のようなクエリは予測不能な内容を生成します。決定的なキーワードを含む事実に基づいたクエリを使用してください

---

例：Python インテグレーションスキルの追加

前提：You.com 検索で httpx ライブラリをラップし、Python のみを使用します。

作成するファイル：

skills/ydc-httpx-integration/
├── SKILL.md
└── assets/
    ├── path_a_basic.py
    ├── test_integration.py
    └── pyproject.toml

tests/ydc-httpx-integration/
└── .gitkeep

テストディレクトリを作成します：

mkdir -p tests/ydc-httpx-integration && touch tests/ydc-httpx-integration/.gitkeep

prompts.jsonl のエントリ：

{"id":"ydc-httpx-integration","input":["Using the ydc-httpx-integration skill, create a working Python application that calls the You.com search API directly with httpx and returns search results. Write integration tests that call the real API and verify the response contains expected keywords. Save everything to the tests/ydc-httpx-integration directory.","Extend the integration to also support content extraction from URLs. Update the integration tests to verify both search and content extraction work with live queries."],"metadata":{"cwd":"tests/ydc-httpx-integration","language":"python"}}