migrate agents to codex

AI Community

Skill notes

Purpose

Migrates Claude agent definitions from .claude/agents/*.md (YAML frontmatter markdown body) to Codex-compatible outputs under .codex/agents/. Preferred output: standalone TOML custom-agent files. Backward-compatible output only: pure-markdown behavioral specifications. The migration strips frontmatter, maps fields to native Codex contracts,

Conversation-First Entry

Bare requests should start with a user-facing action menu, not a wall of CLI flags. Follow the shared contract in ../migrate-to-codex/references/conversational-migration-contract.md. Default menu for underspecified requests: Assess one agent

Advanced CLI

Preferred wrappers: python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --agent example-agent-a --dry-run --json python3 .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py --preview --agent example-agent-a --json python3 .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py --agent example-agent-a --json Power-user engine:

Prerequisites

Python 3.11+ available Sibling skill exists: .codex/skills/migrate-to-codex/ (provides shared functions) .codex/agents/ directory will be created by the script if missing .codex/config.toml exists with MCP server definitions Gold standard reference if present: a previously migrated agent artifact under

Format: Markdown vs TOML

Official Codex custom-agent format is TOML under .codex/agents/*.toml. Use: --format toml for new migrations --format md only for backward-compatible markdown outputs Rules:

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
AI
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 Β· heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io Β· no license declared
Token usage
Heavy
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
Python >=3.11
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Step 1: Assess Complexity & Resolve Dependencies

Context: User provides an agent name, a list, `--all`, or a bare request that still needs the menu/front-door routing. Before running the backend: bare request -> show the family menu from the shared conversational contract explicit action + explicit target -> route directly

02
Step 2: Map Fields

Apply the field mapping from agent-field-mapping.md. Key transformations: Claude Field Β· Codex Section `name` Β· `# Agent: {Title}`

03
Step 2.6: Convert Embedded Delegation Sites

If the source agent or its companion references contain embedded delegation sites, apply the decision process in subagent-migration-guide.md. Decision rules: Reusable named role β†’ create `.codex/agents/<name>.toml`

04
Step 2.5: Verify Domain Content (Tier 2-3 only)

WHY THIS STEP EXISTS: Claude agent bodies drift from the codebase. Route constants get renamed, helper functions get deleted, test infrastructure gets replaced. If you copy stale domain examples into the companion reference, the Codex audit will catch them β€” but at the cost of an extra audit cycle (~500K-1.5M tokens). Verify first, write once.

05
Step 3: Execute Migration

Step 3: Execute Migration

06
Step 4: Validate

Step 4: Validate

07
Step 5: Native Codex Compliance Audit (inline native sub-agent)

When: After Step 4 validation passes β€” before reporting to the user. Review-only entry: If an agent already exists under `.codex/agents/` and the tracker says it is `pending_native_review`, this step may be invoked directly as a read-only single-agent review flow. In that entry path, audit first, present findings plus next actions, and auto-record `native` by default

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.