Back to Details

agent-converter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Converter

Agent 转换器

Objective

目标

Convert agent definitions between two formats:
  1. Markdown format (
    .md
    with YAML frontmatter) — Rich format with explicit tool restrictions
  2. TOML format (
    .toml
    ) — Simple format for Codex agents with sandbox modes
在两种格式之间转换Agent定义：
  1. Markdown格式（
    .md
    ，带YAML前置元数据）—— 支持明确工具限制的富格式
  2. TOML格式（
    .toml
    ）—— 适用于带沙箱模式的Codex风格Agent的简易格式

Inputs

输入项

  • Source file: Path to an agent 
    .md
    file (or directory of agents)
  • Output format: 
    toml
    (default) or 
    md
  • Output directory: Where to write converted files (default: same as source)
  • 源文件：Agent的
    .md
    文件路径（或Agent所在目录）
  • 输出格式：
    toml
    （默认）或
    md
  • 输出目录：转换后文件的写入路径（默认：与源文件同目录）

Commands

命令

Convert single agent MD → TOML

转换单个Agent（MD → TOML）

bash
python3 skills/agent-converter/scripts/convert_agent.py <input.md> [--output <dir>]
bash
python3 skills/agent-converter/scripts/convert_agent.py <input.md> [--output <dir>]

Convert all agents in directory

批量转换目录下所有Agent

bash
python3 skills/agent-converter/scripts/convert_agent.py --batch <input_dir> [--output <dir>]
bash
python3 skills/agent-converter/scripts/convert_agent.py --batch <input_dir> [--output <dir>]

Convert TOML → MD

转换TOML → MD

bash
python3 skills/agent-converter/scripts/convert_agent.py <input.toml> --to-md [--output <dir>]
bash
python3 skills/agent-converter/scripts/convert_agent.py <input.toml> --to-md [--output <dir>]

Format Mapping

格式映射

MD FrontmatterTOML Field
name
(derived from filename)
description
Included in 
developer_instructions
tools
Mapped to 
sandbox_mode
Markdown body
developer_instructions
MD前置元数据TOML字段
name
（从文件名派生）
description
纳入
developer_instructions
tools
映射到
sandbox_mode
Markdown正文
developer_instructions

Tool → Sandbox Mode Mapping

工具→沙箱模式映射

ToolsSandbox Mode
Read
, 
Grep
, 
Glob
only
read-only
Any Write/Edit tools
allow-edits
No tools specified
allow-edits
(default)
工具沙箱模式
仅包含
Read
, 
Grep
, 
Glob
read-only
包含任何写入/编辑工具
allow-edits
未指定工具
allow-edits
（默认）

Sandbox Mode → Tool Mapping (reverse)

沙箱模式→工具映射（反向）

Sandbox ModeTools
read-only
Read
, 
Grep
, 
Glob
allow-edits
Read
, 
Write
, 
Edit
, 
Bash
, 
Glob
, 
Grep
沙箱模式工具
read-only
Read
, 
Grep
, 
Glob
allow-edits
Read
, 
Write
, 
Edit
, 
Bash
, 
Glob
, 
Grep

Example Conversion

转换示例

Input: 
explorer.md

输入：
explorer.md

markdown
---
name: explorer
description: >
  Read-only codebase explorer.
tools:
  - Read
  - Grep
  - Glob
---
markdown
---
name: explorer
description: >
  只读代码库探索器。
tools:
  - Read
  - Grep
  - Glob
---

Explorer — Read-Only Codebase Navigator

Explorer — 只读代码库导航器

You are a read-only explorer agent...
undefined
你是一个只读的探索器Agent...
undefined

Output: 
explorer.toml

输出：
explorer.toml

toml
sandbox_mode = "read-only"

developer_instructions = """
Role: Read-only codebase explorer.

Tools: Read, Grep, Glob

---
toml
sandbox_mode = "read-only"

developer_instructions = """
角色：只读代码库探索器。

工具：Read, Grep, Glob

---

Explorer — Read-Only Codebase Navigator

Explorer — 只读代码库导航器

You are a read-only explorer agent... """
undefined
你是一个只读的探索器Agent... """
undefined

Workflow

工作流程

  1. Parse source file (MD or TOML)
  2. Extract metadata and instructions
  3. Map format-specific fields
  4. Write output in target format
  5. Report conversion summary
  1. 解析源文件（MD或TOML）
  2. 提取元数据和说明内容
  3. 映射格式专属字段
  4. 以目标格式写入输出文件
  5. 生成转换汇总报告

Error Handling

错误处理

ErrorResolution
Missing frontmatterTreat as plain markdown, use defaults
Invalid TOMLReport parse error with line number
Unknown toolsWarn and include in output as-is
File existsPrompt user or use 
--force
to overwrite
错误类型解决方法
缺少前置元数据视为纯Markdown，使用默认配置
无效TOML报告包含行号的解析错误
未知工具发出警告并原样保留在输出中
文件已存在提示用户或使用
--force
参数覆盖

References

参考资料

  • Format specification: 
    skills/agent-converter/references/format-spec.md
  • Example agents: 
    .agents/sub-agents/
  • 格式规范：
    skills/agent-converter/references/format-spec.md
  • 示例Agent：
    .agents/sub-agents/