workflow-skill-creator

Workflow-to-Skill Distiller

完了したワークフローを、再利用可能なエージェントスキルに変換します。具体的には、すでに行われたやり取りやワークフローからパターンを抽出し、パッケージ化します。

注意

コードや SKILL.md の内容を書く前に、必ずフェーズ 1（ブレインストーミング）を完了してください。 ブレインストーミングを省略すると、スキルが硬直的すぎたり、曖昧すぎたりする可能性があります。ブレインストーミングの対話は、このプロセスで最も重要な部分です。

フェーズ 1：ブレインストーミング（必須）

ユーザーと反復的な対話を行ってください。すべての質問を一度に尋ねてはいけません。以下の質問集から関連する質問を 2～3 個選び、理解を深めながら、追加の質問をしてください。

ラウンド 1：ワークフローを理解する

まず、ワークフローから把握した内容を要約してから、次の質問をしてください。

1. 「ワークフローについて、次のように理解しました：[summary]。これは正確ですか？変更したい点はありますか？」
2. 「このワークフローで想定される入力と出力は何ですか？」
3. 「このワークフローはどのくらいの頻度で実行する予定ですか？繰り返し実行しますか、それとも一度きりですか？」

ラウンド 2：柔軟性とエラー処理

ワークフローで特定した各ステップについて、どの程度厳密にするかを確認してください。

1. 「[step X] で主要な方法が失敗した場合（例：API が停止している、結果がないなど）、エージェントはどのように対応すべきですか。（a）対応方法をあなたに尋ねる、（b）代替方法を自動的に試す、（c）エラーを明確に示して失敗する」
2. 「方法が重要なステップ（例：特定のデータベースを使う必要がある）と、妥当な方法であれば何でもよいステップはありますか？」
3. 「エッジケースはユーザーに知らせずに処理しますか、それともユーザーに提示しますか？」

ラウンド 3：依存関係とリソース

これらの質問をする前に、インストール済みのスキルのうち、ワークフローと重複するものを確認してください。既存の science バンドルのスキルで対応できるステップがある場合、新しいスキルは必ずそれを参照してください。自己完結型にする選択肢を提示してはいけません。

1. 「このワークフローでは、[existing skill X, skill Y] が対応する機能を使用していることに気付きました。新しいスキルでは、これらを再実装せずに参照します。他に取り入れてほしいツールやスキルはありますか？」
2. 「このワークフローで使用するサービスについて、既存のスキルでまだ扱われていない API のレート制限で、注意すべきものはありますか？」
3. 「このスキルの作成にあたり、科学的な背景情報として重要なファイルはありますか？たとえば、API ドキュメント、参考論文、サンプルデータセット、分野固有のメモなどです。あれば共有してください。内容をスキルの参考資料に取り込みます。」

ラウンド 4：範囲と形式

1. 「ワークフローでは［X、Y、Z］を扱いました。これらすべてをスキルにまとめるべきでしょうか？それとも、含めるべき重要な機能がほかにありますか？逆に、含めないほうがよいものはありますか？」
2. スキルにコードが必要かどうかを判断します。いずれかの手順に API の呼び出し、データの処理、ファイルの読み書き、結果の計算が含まれる場合、スキルにはコードが必要です。その場合は、CLI パターンを標準として使用してください。すべての手順が推論、既存のツールの連携、またはプログラムによる処理を一切伴わない文書化された手順への準拠のみである場合に限り、テキストのみの指示スキルを使用してください。評価内容を、わかりやすい言葉でユーザーに確認します。
   • コードが必要な場合：「これらの手順の一部には［API からのデータ取得／ファイルの処理／結果の計算］が含まれるため、エージェントが実行できるヘルパースクリプトを作成します。スクリプトには search、fetch、analyze などのシンプルなコマンドを用意します。ご自身でコードを書く必要はありません。この方針でよろしいですか？」
   • コードが不要な場合：「このワークフローは一連の手順に従い、既存のツールを使うもので、新しいコードは必要ありません。エージェントが従う明確な指示として作成します。この方針でよろしいですか？」
3. ヘルパースクリプトを作成する場合：「スクリプトには次のコマンドを用意することを考えています。［平易な言葉で提案するコマンド。例：『タンパク質を検索する』『結果を取得する』『配列を比較する』］追加または変更したい点はありますか？」
4. 「スキルの名前は何にしますか？名前の候補：[suggestion]」

ラウンド 5：テスト（任意）

1. 「スキルが意図したとおりに動作するかを確認するための、サンプルクエリと期待する回答を提示していただけますか？たとえば、『［質問］と尋ねた場合、スキルは［回答］を返す』という形式です。これは任意ですが、開発中の検証に役立ちます。」

ブレインストーミングの完了条件

以下のすべてに自信を持って回答できたら、フェーズ 2 に進む準備が整っています。

• ワークフローの目的と範囲は何か？
• 入力と出力は何か？
• どの手順が厳密で、どの手順が柔軟か？
• 参照すべき既存のスキルはどれか？
• 必要な新しいスクリプトはあるか？（ある場合はどれか？）
• 適用されるレート制限は何か？
• エラーはどのように処理するか？
• ワークフローにコードは必要か？（必要な場合 → CLI パターン、不要な場合 → 指示のみ）
• スキルはどこにインストールするか？（ローカル、グローバル、またはカスタムパス）
• 検証用のサンプルクエリと回答はあるか？

フェーズ 2：スキルの設計

設計ドキュメント（成果物／実装計画）を作成し、ユーザーに提示して承認を求めます。ドキュメントには以下を含めてください。

1. スキル名と説明（YAML フロントマターのルールに準拠：名前は 64 文字以内、小文字とハイフンを使用。説明は 1024 文字以内）。
2. ディレクトリ構成。計画しているすべてのファイルとインストール先（ローカル、グローバル、またはカスタム。ルール 7 を参照）を示します。
3. 参照する既存のスキルと、それぞれの理由。
4. 新しいスクリプト（ある場合）と、提案するサブコマンドおよび引数。
5. 既存のスキルで対応できない API に対するレート制限戦略。
6. 手順ごとのエラー処理戦略。

フェーズ 3 に進む前に、ユーザーから明示的な承認を得てください。

フェーズ 3：実装

指針

スキルの実装に関する一般的なガイドライン：

• python や python3 ではなく、uv run を使用してください。
• Python 3 の標準インストールに含まれる標準ライブラリ（urllib を推奨）を優先してください。可能であれば、追加のインストールが必要なライブラリは避けてください。
• レート制限は文書化し、コードで遵守する必要があります。同じマシンを共有する並行サブエージェントが全体として制限を遵守できるよう、ファイルロックベースのレート制限を優先してください。プロセス間で安全に動作する標準的な実装については、Science Skills バンドル内の他のスキルを参照してください。
• スキルの出力は500行未満にするか、ファイルにリダイレクトしてください。長い出力ファイルは、関連フィールドを抽出するためにプログラムで処理してください。
• スキル名と YAML の name: フィールドには、ハイフンを使用することを推奨します。

ルール 1：既存スキルの再利用

ワークフローで、インストール済みの既存スキルがカバーする機能を使用する場合、新しい SKILL.md では再実装するのではなく、そのスキル名を参照しなければなりません。SKILL.md に Dependencies セクションを設け、必要なスキルとそれぞれの簡単な理由を記載してください。

ルール 2：新しい API のレート制限

既存のスキルでカバーされていない API の操作では、生成する CLI スクリプトにレート制限を実装しなければなりません。レート制限のコードを書く前に、API の公式なレート制限ガイドラインを調べてください。ブレインストーミング中にユーザーから提供されたドキュメントを確認したうえで、API の公開ドキュメントをオンラインで検索してください。文書化されたレート制限が見つからない場合は、デフォルトで毎秒1リクエストとします。レート制限のパターンは、references/cli_script_template.py の CLI テンプレートに組み込まれています。RateLimitError クラスと、API クライアントの _request メソッドを参照してください。

主な要件：

• 時間の計測には time.time() ではなく、time.monotonic() を使用してください。
• 文書化されたレート制限に基づいて遅延時間を計算してください。
• 一時的なエラー（5xx）に対して、指数バックオフによる再試行を実装してください。
• HTTP 429 を受信した場合は、専用の RateLimitError を発生させてください。
• エージェントが進捗を確認できるよう、再試行のたびに stderr に記録してください。
• エラーメッセージには URL とレート制限値を含めてください。
• 再試行できない HTTP エラー（例：400、403、404）が発生した場合は、ステータスコードだけでなく、レスポンス本文を読み取ってエラーメッセージに含めてください。API のレスポンス本文には、エージェントによる自己修正に役立つ実行可能な詳細（例：「無効なパラメーター」）が含まれています。

ルール 3：CLI スクリプトのパターン（コードが必要な場合のデフォルト）

これをデフォルトの選択肢とします。 ワークフローに API 呼び出し、データ処理、ファイル I/O、計算、その他のプログラムによる作業が少しでも含まれる場合は、サブコマンドを備えた argparse の複数コマンド対応 CLI スクリプトを作成してください。references/cli_script_template.py のテンプレートに従ってください。

主な要件：

• ワークフローの各主要ステップをサブコマンドにしてください。
• すべてのサブコマンドで、結果をファイルに書き込む --output を受け付けてください。
• JSON の出力には indent=2 を指定した json.dump を使用してください。
• 出力ファイルのパスを含む成功メッセージを表示してください。
• エラー時はコード1で終了してください。
• --limit などの引数は必須にしてください（暗黙のデフォルト値は設定しないでください）。これにより、上限が黙って適用された結果を取得しているにもかかわらず、エージェントが「すべて」の結果を取得したと思い込むことを防ぎ、値を明示的に指定させることができます。

ルール 4：ファイルへの出力をデフォルトにする

すべてのスクリプトとワークフローは、標準出力ではなくファイルに出力しなければなりません。標準出力には、「成功しました。データを書き込みました：results.json」のような短いステータスメッセージだけを出力してください。これは次の理由から重要です。

• API のレスポンスは非常に大きくなる場合があり、ターミナル出力では途中で切り捨てられます。
• ファイル出力はトークン効率に優れています。エージェントは jp または Python のワンライナーを使って、必要なフィールドだけを読み取れます。
• 標準出力への大量の出力は、コンテキストウィンドウの領域を無駄に消費します。

ルール 5：指示のみのパターン（コードが不要な場合のみ）

ワークフローにプログラムによる作業が一切不要な場合にのみ、このパターンを使用してください。つまり、すべてのステップがオーケストレーション、推論、複数のスキル間の連携、または記述されたプロトコルへの準拠のみで構成される場合です。いずれかのステップでコードが必要な場合（API 呼び出し、データ処理、ファイル I/O など）は、代わりにルール 3 の CLI パターンを使用してください。構造化されたワークフローセクションを含む SKILL.md を作成してください。

## Workflow

### 1. Step Name
- Description of what to do
- Which skill to use and how

### 2. Next Step
...

ルール 6：SKILL.md の構成

生成するすべての SKILL.md は、次の構成に従う必要があります。

---
name: {skill-name}
description: >-
  {description}
---

# {Skill Title}

## Overview
{Brief description of what the skill does.}

## Dependencies
{List of required skills, if any.}

## Quick Start
{Minimal example to get started.}

## Utility Scripts (if CLI-based)
{Document each subcommand with examples.}

## Workflow (if instruction-only)
{Numbered steps with clear instructions.}

## Rate Limiting (if applicable)
{Document rate limits and how they are enforced.}

## Common Mistakes
{List 2-3 common pitfalls.}

ルール 7：スキルの配置

スキルはローカル（プロジェクト固有、ワークスペースごと）またはグローバル（すべてのプロジェクトで利用可能）にインストールできます。ローカル、グローバル、カスタムのインストール先のいずれを希望するか、ユーザーに確認してください。

エージェント CLI ごとのスキルパス（ローカルパスはプロジェクトルートからの相対パスです）：

• Claude Code：ローカル .claude/skills/、グローバル ~/.claude/skills/
• Codex：ローカル .agents/skills/、グローバル ~/.agents/skills/
• Antigravity 2.0：ローカル .agents/skills/、グローバル ~/.gemini/config/skills/
• Gemini CLI：ローカル .gemini/skills/、グローバル ~/.gemini/skills/
• OpenCode：ローカル .opencode/skills/、グローバル ~/.config/opencode/skills/

その他の CLI については、ローカルとグローバルのスキルパスを自分で調べてください。

フェーズ 4：検証

実装が完了したら、次の手順を実行してください。

1. 新しいスキルを呼び出す自然言語のプロンプトを使ってエージェントを実行し、スキルを手動でテストしてください。

2. ブレインストーミング中にサンプルのクエリ／回答が提示されていた場合は、スキルに入力して、出力が期待どおりであることを確認してください。