converting-email-templates

メールテンプレートの変換

目的

ほかのメールサービスプロバイダーのメールテンプレートを、Mailtrap 対応の Handlebars 構文に自動変換します。Python スクリプトによる決定論的なパターン変換と、LLM の知能による複雑なエッジケースへの対応の両方を行います。

関連スキル： using-email-templates（Handlebars 構文、API テンプレート送信）、sending-emails（ストリームのベースと認証）、authorizing-api-requests（トークン、環境変数、account_id の解決 — 変換後にテンプレートを作成したり、Templates API で送信したりする際に必要です）。

入力

• ソースプロバイダー（必須）：sendgrid、mailgun、mandrill-handlebars、mandrill-mergetags、postmark、brevo、または ses
• 入力：単一のテンプレートファイルのパス、.html テンプレートファイルを含むディレクトリ、またはインラインで貼り付けた HTML
• 出力ディレクトリ（任意）：入力ファイルの隣にある /converted/ サブディレクトリがデフォルトです

ユーザーがソースプロバイダーを指定しない場合は、作業を進める前に尋ねてください。ユーザーがテンプレート HTML をインラインで提供（チャットに貼り付け）した場合は、まず一時的な .html ファイルに保存してください。

ワークフロー

ステップ 1：モードを判定する

高速モード（デフォルト）：決定論的な変換パターンを持つプロバイダーに使用します。Python スクリプトで確実に処理できます。

詳細モード：次の場合に実行します。

• プロバイダーが brevo で、テンプレートにネストされたループ、複数のフィルター、または複雑にネストされた条件が含まれている
• スクリプトが LLM の判断を活用できるパターンを検出する
• ユーザーが明示的に詳細モードをリクエストする
• インライン HTML が提供される（LLM による変換を直接実行する）

ステップ 2：コンバータースクリプトを実行する

Python コンバータースクリプトを実行します。

python3 {skill_dir}/scripts/converter.py \
  --provider {provider} \
  --input {input_path} \
  --output {output_dir}

{skill_dir} は、この SKILL.md ファイルが格納されているディレクトリです。

出力を確認します。

• 終了コード 0：フラグのないクリーンな変換です。ステップ 4 に進みます。
• 終了コード 1：フラグ付きで変換が完了しました。ステップ 3 に進みます。
• 終了コード 2：エラーです。ユーザーに報告し、停止します。

変換された各テンプレートと同じ場所に生成された .report.txt ファイルを読み取ります。一括変換の場合は、_summary.txt も読み取ります。

注： フラグがある場合、スクリプトは自動的に次の処理を行います。

• 変換後のファイルの先頭に `` コメントを追加する
• サポートされていない構文を `` HTML コメントで囲み、Mailtrap エディターに貼り付けてもパーサーエラーが発生しないようにする

ステップ 3：フラグに対応する（詳細モード）

レポート内の各フラグについて、次の手順を実行します。

1. 元のテンプレートでフラグが付いた行を読む。
2. 該当するルールと推奨される対応について、references/conversion-rules.md を参照する。
3. フラグを分類する。
   • アプリケーション層の変更が必要（例：formatDate、比較ヘルパー）：テンプレート内では解決できません。アプリケーションコードで必要な変更を明確に説明して、ユーザーに報告します。置き換えに使う変数名を提案します。
   • テンプレートレベルで修正可能（例：Brevo のネストされたループ、Mandrill の mc:edit 領域）：LLM の判断で変換を適用します。変更を書き込む前に、変換前後をユーザーに示して確認を求めます。
   • 曖昧（例：Postmark の終了タグの不一致）：元のコンテキストと変換後の出力の両方をユーザーに示します。確認を求めます。

フラグはカテゴリごとにまとめて提示します。

## Conversion Complete

### Auto-converted: [count] changes
[Brief summary or collapsed details]

### Needs your application code: [count] flags
[For each: what to change, why, suggested variable name]

### Needs verification: [count] flags
[For each: show before/after, ask for confirmation]

ステップ 4：結果を提示する

単一ファイルの場合：

Converted: {filename}
Changes: [count] | Flags: [count]
Output: {output_path}

[Show the conversion report summary]
[If flags exist, show the categorized flag breakdown from Step 3]

一括変換の場合：

Converted: [count] files
Total changes: [count] | Total flags: [count]
Clean: [count] files | Needs review: [count] files
Output: {output_dir}

[Show the summary report]
[List files needing review with their specific flags]

Step 5: API フィールドのマッピングに関する注意

テンプレート変換後は、API 側で必要な変更を必ずユーザーに伝えてください。以下のクイックマッピング表を参照してください。

プロバイダー	旧テンプレートフィールド	旧変数フィールド	Mailtrap フィールド	Mailtrap 変数
SendGrid	template_id	personalizations[].dynamic_template_data	template_uuid	template_variables
Mailgun	template	t:variables	template_uuid	template_variables
Mandrill	template_name	global_merge_vars + merge_vars	template_uuid	template_variables
Postmark	TemplateId/TemplateAlias	TemplateModel	template_uuid	template_variables
Brevo	templateId	params	template_uuid	template_variables
Amazon SES	TemplateName/TemplateArn	TemplateData	template_uuid	template_variables

変換したプロバイダーの行だけを表示してください。

インライン変換（ファイルなし）

ユーザーがファイルパスではなく、テンプレート HTML をチャットに直接貼り付けた場合：

1. 元のプロバイダーを特定します（明記されていない場合は確認します）。
2. LLM の知能を使って、references/conversion-rules.md の変換ルールを直接適用します。
3. 変換結果では、未対応の構文を `` HTML コメントで囲みます（スクリプトと同じ形式）。これにより、ユーザーが出力を Mailtrap に貼り付けたときにエディターエラーが発生しなくなります。
4. フラグがある場合は、解決が必要なフラグ付きパターンの数を記した `` コメントを変換結果の先頭に追加します。
5. 変更点の一覧とともに、変換後の Handlebars 出力を提示します。
6. アプリケーション層での変更が必要なパターンにフラグを付けます。
7. 結果をファイルに保存するかどうかをユーザーに確認します。

このモードでは、スクリプトに渡すファイルがないため、常に Deep モード（LLM）を使用します。

ルール

• **フラグ付きパターンを黙って省略しないでください。**すべてのフラグをユーザーに報告します。
• **元のファイルを変更しないでください。**変換後の出力は常に出力ディレクトリに保存します。
• **HTML 構造を保持してください。**変更するのはテンプレート構文（変数、条件分岐、ループ、ヘルパー）のみです。HTML タグ、属性、CSS、テンプレート以外のコンテンツには手を加えないでください。
• **判断に迷ったらフラグを付けてください。**パターンが曖昧な場合は、誤った変換を行わず、手動確認のためにフラグを付けます。
• **件数を報告してください。**変更数とフラグ数を必ず表示し、ユーザーが作業範囲を把握できるようにします。
• **一度に扱うプロバイダーは1つだけです。**ディレクトリに複数のプロバイダーのテンプレートが含まれる場合は、ユーザーに分けるか、バッチの対象プロバイダーを指定するよう依頼します。