Agent Converter

Objective

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

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)

Commands

Convert single agent MD → TOML

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

Convert all agents in directory

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

Convert TOML → MD

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

Format Mapping

name

description

developer_instructions

tools

sandbox_mode

developer_instructions

Tool → Sandbox Mode Mapping

Read

Grep

Glob

read-only

allow-edits

allow-edits

Sandbox Mode → Tool Mapping (reverse)

read-only

Read

Grep

Glob

allow-edits

Read

Write

Edit

Bash

Glob

Grep

Example Conversion

Input:

explorer.md

---
name: explorer
description: >
  Read-only codebase explorer.
tools:
  - Read
  - Grep
  - Glob
---

# Explorer — Read-Only Codebase Navigator

You are a read-only explorer agent...

Output:

explorer.toml

sandbox_mode = "read-only"

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

Tools: Read, Grep, Glob

---

# Explorer — Read-Only Codebase Navigator

You are a read-only explorer agent...
"""

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

Error Handling

--force

References

• Format specification:

  skills/agent-converter/references/format-spec.md

• Example agents:

  .agents/sub-agents/