converter

转换器 — 跨平台 Skill 转换器

将 AgentOps 技能解析为通用的 SkillBundle 格式，然后转换为目标 Agent 平台的格式。

中间格式 SkillBundle 可确保转换忠实准确：每个目标都读取相同的解析后契约，因此渲染错误属于目标适配器错误，而不是对源内容的悄然重新解读。如果两个目标对某项技能的内容有不同理解，由 bundle（而非任一输出）来裁定。

此转换器不负责维护已发布的 skills-codex/** 投影：该路径由 scripts/regen-all.sh 通过 scripts/codex-sync.sh 生成并设有门禁。此转换器是临时的、目录树外的导出器（Codex、Cursor），写入 .agents/projections/converter/；它绝不修改 skills-codex/**。如果已发布的 Codex 副本与此导出器生成的内容不一致，以已发布的路径为准。

指定的失败模式——投影编辑：手动编辑转换后的输出以修复渲染问题，而下一次转换会将其彻底覆盖。

反模式：将新输出合并到现有目标目录，以保留本地调整。正确做法：修复源技能或适配器，然后重新运行清理式转换。

约束

• 将规范源技能视为只读，因为转换不得修改正在翻译的契约。
• 仅对明确指定的目标目录执行清理式写入，防止转换后残留过时资源或删除无关路径。
• 如果复制的资源未能保持一致，或目标格式验证失败，则应报错，因为不完整的 bundle 无法作为可用转换结果。

流程

转换器运行一个三阶段流程：

parse --> convert --> write

阶段 1：解析

读取源技能目录并生成 SkillBundle：

• 从 SKILL.md 提取 YAML frontmatter（位于 --- 标记之间）
• 收集 Markdown 正文（闭合 --- 之后的所有内容）
• 列出 references/ 和 scripts/ 中的所有文件
• 组装为 SkillBundle（参见 references/skill-bundle-schema.md）

阶段 2：转换

将 SkillBundle 转换为目标平台的格式：

目标	输出格式	状态
codex	Codex SKILL.md + prompt.md	已实现
cursor	Cursor .mdc 规则 + 可选 mcp.json	已实现

Codex 适配器会生成一个包含 YAML frontmatter（name、description）以及经过改写的正文内容的 SKILL.md，并生成一个 prompt.md。默认模式为模块化：参考文档、脚本和资源会以文件形式复制，SKILL.md 中则包含本地资源索引，而不是内联所有内容。可选的内联模式保留了旧版行为，会追加内联参考内容和脚本代码块。Codex 输出会规范化其他运行时的调用语法和路径，将不受支持的原语标签改写为与运行时无关的表述，并保留现有的扁平 ao CLI 命令。它还会去重重复的运行时标题，同时保留各节内容。非生成的资源文件和目录会经过一致性检查后复制。如有需要，描述会在单词边界处截断为不超过 1024 个字符。

Cursor 适配器会生成一个 <name>.mdc 规则文件，其中包含 YAML frontmatter（description、globs、alwaysApply: false）和正文内容。参考内容会内联到正文中，脚本则作为代码块包含在内。输出会控制在最多 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 的 frontmatter、Markdown 正文以及所有 references/ 和 scripts/ 文件解析为 SkillBundle。
2. Codex 适配器会将此包转换为 SKILL.md（正文 + 内联引用 + 作为代码块的脚本）和 prompt.md（引用该技能的 Codex 提示词）。
3. 输出写入 .agents/projections/converter/codex/council/。

结果： 一个兼容 Codex、可供 OpenAI Codex CLI 使用的技能包。

将所有技能批量转换为 Cursor 规则

调用方请求： 将所有规范技能转换为 Cursor 格式。

执行过程：

1. 转换器会扫描 skills/ 下的每个目录，并将其解析为 SkillBundle。
2. Cursor 适配器会将每个包转换为包含 YAML frontmatter 和正文内容的 .mdc 规则文件，并将大小控制在 100KB 以内。引用 MCP 服务的技能还会获得一个 mcp.json 存根文件。
3. 每个技能的输出都写入 .agents/projections/converter/cursor/<skill-name>/。

结果： 所有技能都可作为 Cursor 规则使用，可直接放入 .cursor/rules/ 目录。

故障排查

问题	原因	解决方案
parse error: no frontmatter found	SKILL.md 缺少由 --- 分隔的 YAML frontmatter 块	添加至少包含 name: 和 description: 字段的 frontmatter，或先对源包运行 Heal Skill
Cursor .mdc 输出缺少引用	Bundle 总大小超出 100KB 的预算限制	转换器会优先省略较大的引用以满足预算。拆分较大的引用文件，或将非必要内容移至外部文档
输出目录中已有旧文件	上次转换的产物仍然存在	这是预期行为——转换器会在写入前删除目标目录，以干净写入。如果旧文件仍然存在，请手动删除 .agents/projections/converter/<target>/<skill>/
--all 跳过某个技能目录	该目录中没有 SKILL.md 文件	确保每个技能目录都包含有效的 SKILL.md。运行 Heal Skill 检测空目录
Codex prompt.md 描述被截断	技能描述超过 1024 个字符	这是有意为之。转换器会在单词边界处截断，以符合 Codex 限制。如果截断位置不合适，请缩短 SKILL.md frontmatter 中的描述
转换未通过直通一致性检查	源技能中的某个资源条目未复制到输出中	确保源条目可读取且可复制（包括嵌套文件）。重新运行转换；此失败是有意设置的，用于防止 skills/ 与转换后输出之间出现偏差

输出规范

• 路径： 默认输出到 .agents/projections/converter/<target>/<skill-name>/，或调用方提供的确切输出目录。
• 文件名： Codex 会生成 SKILL.md、prompt.md 和复制的资源；Cursor 会生成 <skill-name>.mdc 和可选的 mcp.json；test 会生成原始 Bundle 表示。
• 格式： 符合目标要求的 UTF-8 文本，包含必需的 frontmatter、重写后的运行时引用以及按字节原样保留的资源；Cursor 输出不超过 100KB。
• 退出代码： 运行 bash skills/converter/scripts/convert.sh <skill-dir> <target> <output-dir> 并要求返回零；将解析、预算、写入或直通一致性检查失败视为非零且未完成。
• 下游交接： 向安装程序或投影检查关卡报告源技能、目标、输出目录、布局、省略的 Cursor 引用（如有）以及验证结果。

质量检查清单

• 源树未更改，输出树中不含上次转换遗留的文件。
• 每个必需的目标文件都能通过相应的 frontmatter/schema 解析，并且所有符合条件的源资源均已包含。
• 特定运行时的重写保留源含义，且不会重新引入已弃用的命令形式或其他运行时的路径。

参考资料

• references/skill-bundle-schema.md -- SkillBundle 交换格式规范

参考文档

• references/skill-bundle-schema.md