converter

Converter — クロスプラットフォームスキルコンバーター

AgentOps スキルを汎用的な SkillBundle 形式に解析し、対象のエージェントプラットフォーム向けに変換します。

中間形式の SkillBundle によって、変換の整合性が保たれます。すべてのターゲットが同じ解析済みの契約を読み込むため、レンダリングの不具合は常にターゲットアダプターの不具合であり、ソースが気付かないうちに別の解釈をされることはありません。2 つのターゲットでスキルの内容に食い違いがある場合、どちらの出力でもなく、バンドルが判断基準になります。

これは、リリース済みの skills-codex/** 投影を管理するものではありません。このパスは scripts/regen-all.sh を通じて scripts/codex-sync.sh が生成し、ゲートします。このコンバーターは場当たり的なリポジトリ外エクスポーター（Codex、Cursor）で、.agents/projections/converter/ 配下に書き込みます。skills-codex/** を変更することはありません。リリース済みの Codex 用ツインとこのエクスポーターに食い違いがある場合は、リリース済みのパスを優先します。

失敗モードの名称 — 投影の編集：変換後の出力を手動で編集してレンダリングの問題を修正し、次回の変換でその変更がクリーン書き込みによって消去されます。

アンチパターン：ローカルの変更を保持するため、新しい出力を既存のターゲットディレクトリにマージすること。是正策：ソーススキルまたはアダプターを修正してから、クリーン書き込みで変換を再実行します。

制約

• 変換によって翻訳対象の契約が変更されないよう、正規ソーススキルは読み取り専用として扱います。
• 変換後も古いリソースが残ったり、無関係なパスが削除されたりしないよう、明示的に指定されたターゲットディレクトリのみをクリーン書き込みします。
• コピーしたリソースの同等性チェックまたはターゲット形式の検証に失敗した場合は、部分的なバンドルは使用可能な変換結果ではないため、処理を失敗させます。

パイプライン

コンバーターは 3 段階のパイプラインを実行します。

parse --> convert --> write

ステージ 1：解析

ソーススキルのディレクトリを読み込み、SkillBundle を生成します。

• SKILL.md から YAML フロントマター（--- マーカーで囲まれた部分）を抽出します
• Markdown 本文（閉じる --- の後のすべて）を収集します
• references/ と scripts/ 内のすべてのファイルを列挙します
• SkillBundle にまとめます（references/skill-bundle-schema.md を参照）

ステージ 2：変換

SkillBundle をターゲットプラットフォームの形式に変換します。

ターゲット	出力形式	ステータス
codex	Codex SKILL.md + prompt.md	実装済み
cursor	Cursor .mdc ルール + 任意の mcp.json	実装済み

Codex アダプターは、YAML フロントマター（name、description）、書き換えられた本文コンテンツ、および prompt.md を含む SKILL.md を生成します。デフォルトモードはモジュール型です。参照ドキュメント、スクリプト、リソースはファイルとしてコピーされ、すべてをインライン化する代わりに、SKILL.md にローカルリソースの一覧が含まれます。任意のインラインモードでは、参照とスクリプトのコードブロックを追記する従来の動作を維持します。Codex 出力では、別のランタイム向けの呼び出し構文とパスを正規化し、サポートされていないプリミティブのラベルをランタイムに依存しない表現に書き換え、現在のフラットな ao CLI コマンドを維持します。また、セクションの内容を保ちながら、重複するランタイム見出しを重複排除します。生成対象ではないリソースファイルとディレクトリは、同等性チェックを行ったうえでコピーされます。必要に応じて、説明は単語の区切りで最大 1024 文字まで切り詰められます。

Cursor アダプターは、YAML フロントマター（description、globs、alwaysApply: false）と本文コンテンツを含む <name>.mdc ルールファイルを生成します。参照は本文にインライン化され、スクリプトはコードブロックとして含まれます。出力は最大 100KB に収まるよう調整されます。合計サイズが上限を超える場合、サイズの大きい参照から順に省略されます。スキルが MCP サーバーを参照している場合は、mcp.json のスタブも生成されます。

ステージ 3：書き込み

変換した出力をディスクに書き込みます。

• 既定の出力ディレクトリ： .agents/projections/converter/<target>/<skill-name>/
• 書き込み方法： クリーン書き込みです。書き込み前に対象ディレクトリを削除します。既存の内容とはマージしません。
• 書き込み拒否ガード： 解決された出力ディレクトリがソースパッケージと同じ場合、それを含む場合（祖先ディレクトリの場合）、またはリポジトリのルートである場合、書き込みステージは処理を拒否します。拒否せずにリダイレクトすることはありません。クリーン書き込みによって、変換時に読み込む必要のあるファイル自体が削除されるためです。

CLI の使い方

# Convert a single skill
bash skills/converter/scripts/convert.sh <skill-dir> <target> [output-dir]
bash skills/converter/scripts/convert.sh --codex-layout inline <skill-dir> codex [output-dir]

# Convert all skills
bash skills/converter/scripts/convert.sh --all <target> [output-dir]

引数

引数	必須	説明
skill-dir	はい（または --all）	スキルディレクトリへのパス（例：skills/council）
target	はい	対象プラットフォーム：codex、cursor、または test
output-dir	いいえ	出力先を上書きします。既定値：.agents/projections/converter/<target>/<skill-name>/
--all	いいえ	skills/ ディレクトリ内のすべてのスキルを変換します
--codex-layout	いいえ	Codex 専用のレイアウトモード：modular（既定）または inline（参照／スクリプトを従来どおりインライン化）

対応する対象

• codex -- OpenAI Codex 形式（SKILL.md + prompt.md）に変換し、ランタイムに依存しない書き換えとフラットな ao CLI の保持を行います。既定では、リソースをコピーし、ローカルリソースのインデックスを含むモジュール形式で出力します。従来どおり参照／スクリプトをインライン化するには、--codex-layout inline を指定します。コピー対象のリソースが見つからない場合は、直ちに失敗します。
• cursor -- Cursor のルール形式（.mdc ルールファイル + 任意の mcp.json）に変換します。出力：<dir>/<name>.mdc および任意で <dir>/mcp.json。
• test -- 生の SkillBundle を構造化された Markdown として出力します。解析ステージのデバッグに役立ちます。

拡張

新しい対象プラットフォームを追加するには：

1. scripts/convert.sh に変換関数を追加します（パターン：convert_<target>）
2. 上記の対象一覧を更新します
3. 対象形式にドキュメントが必要な場合は、references/ に参照ドキュメントを追加します

例

単一のスキルを Codex 形式に変換する

呼び出し元の依頼： skills/council を Codex 形式に変換してください。

処理内容：

1. コンバーターが skills/council/SKILL.md のフロントマター、Markdown 本文、および references/ と scripts/ 内のファイルを解析し、SkillBundle にまとめます。
2. Codex アダプターがバンドルを変換し、SKILL.md（本文 + インライン化された参照 + コードブロックとしてのスクリプト）と、スキルを参照する Codex プロンプト prompt.md を作成します。
3. 出力は .agents/projections/converter/codex/council/ に書き込まれます。

結果： OpenAI Codex CLI ですぐに使用できる、Codex 互換のスキルパッケージが作成されます。

すべてのスキルを Cursor ルールに一括変換する

呼び出し元の依頼： すべての正規スキルを Cursor 形式に変換してください。

処理内容：

1. コンバーターが skills/ 内のすべてのディレクトリをスキャンし、それぞれを解析して SkillBundle にまとめます。
2. Cursor アダプターが各バンドルを、YAML フロントマターと本文を含む .mdc ルールファイルに変換します。ファイルサイズは最大 100KB に収まるよう調整されます。MCP サーバーを参照するスキルには、mcp.json のスタブも作成されます。
3. 各スキルの出力は .agents/projections/converter/cursor/<skill-name>/ に書き込まれます。

結果： すべてのスキルが Cursor ルールとして利用可能になり、.cursor/rules/ ディレクトリに配置してすぐに使えます。

トラブルシューティング

問題	原因	解決策
parse error: no frontmatter found	SKILL.md に --- で区切られた YAML フロントマターのブロックがありません	name: と description: のフィールドを含むフロントマターを追加するか、先にソースパッケージで Heal Skill を実行してください
Cursor の .mdc 出力に参照がありません	バンドルの合計サイズが 100KB の上限を超えました	コンバーターは上限内に収めるため、サイズの大きい参照から省略します。大きな参照ファイルを分割するか、必須ではない内容を外部ドキュメントに移してください
出力ディレクトリに古いファイルが残っています	前回の変換で生成されたファイルが残っています	これは想定された動作です。コンバーターは書き込み前に対象ディレクトリを削除してから書き込みます。古いファイルが残っている場合は、.agents/projections/converter/<target>/<skill>/ を手動で削除してください
--all がスキルディレクトリをスキップします	ディレクトリに SKILL.md ファイルがありません	各スキルディレクトリに有効な SKILL.md が含まれていることを確認してください。Heal Skill を実行して空のディレクトリを検出してください
Codex の prompt.md の説明が途中で切れています	スキルの説明が 1024 文字を超えています	これは仕様です。コンバーターは Codex の制限に合わせるため、単語の区切りで説明を切り詰めます。切り詰められる位置が不自然な場合は、SKILL.md のフロントマターにある説明を短くしてください
passthrough parity check で変換に失敗します	ソーススキルのリソースエントリが出力にコピーされませんでした	入れ子のファイルを含め、ソースのエントリが読み取り可能でコピー可能であることを確認してください。変換を再実行してください。skills/ と変換後の出力の不整合を防ぐため、この失敗は意図されたものです

出力仕様

• パス： デフォルトでは .agents/projections/converter/<target>/<skill-name>/、または呼び出し元から指定された出力ディレクトリをそのまま使用します。
• ファイル名： Codex は SKILL.md、prompt.md、コピーされたリソースを出力します。Cursor は <skill-name>.mdc と任意の mcp.json を出力します。test は未加工のバンドル表現を出力します。
• 形式： 必須のフロントマター、書き換えられたランタイム参照、バイト単位でそのままコピーされたリソースを含む、対象で有効な UTF-8 テキストです。Cursor の出力は 100KB 以内に収まります。
• 終了コード： bash skills/converter/scripts/convert.sh <skill-dir> <target> <output-dir> を実行し、終了コードが 0 であることを確認してください。解析、予算、書き込み、または passthrough parity の失敗は、ゼロ以外かつ未完了として扱ってください。
• 後続工程への引き渡し： ソーススキル、対象、出力ディレクトリ、レイアウト、省略された Cursor の参照（ある場合）、検証結果をインストーラーまたは projection gate に報告してください。

品質チェックリスト

• ソースツリーに変更がなく、出力ツリーに前回の変換で残ったファイルがありません。
• 対象に必要なすべてのファイルが対象のフロントマター／スキーマに従って解析でき、条件を満たすソースリソースがすべて含まれています。
• ランタイム固有の書き換えによってソースの意味が保たれ、非推奨のコマンド形式や別ランタイム用のパスが再導入されていません。

参考資料

• references/skill-bundle-schema.md -- SkillBundle の相互運用形式の仕様

参照ドキュメント

• references/skill-bundle-schema.md